openshift
[enterprise-4.10] Issue in file post_installation_configuration/cluster-tasks.adoc
Which section(s) is the issue in?
Automatic defragmentation
What needs fixing?
The documentation states that "The etcd Operator automatically defragments disks. No manual intervention is needed" and to "Verify that the defragmentation process is successful by viewing one of these logs". However, the example log output shown just states the current level of fragmentation, not whether a process ran or was successful or unsuccessful.
I think it would be more helpful to the reader if there were log output examples showing what to look for in a successful defrag and an unsuccessful defrag. As it is, the reader does not have the context or additional knowledge to interpret the log example shown.
Direct link to the section of the "Automatic defragmentation" section of the docs: https://docs.openshift.com/container-platform/4.11/post_installation_configuration/cluster-tasks.html#automatic-defrag-etcd-data_post-install-cluster-tasks
Hi @patrickstrick - When you can, please take a look at this update to the docs and let me know if the new examples are more helpful. Thanks.
Preview link (VPN required): http://file.rdu.redhat.com/lahinson/etcd-auto-defrag/post_installation_configuration/cluster-tasks.html#etcd-defrag_post-install-cluster-tasks
@lahinson Thank you! I see the examples of a successful and unsuccessful defrag in there. This is exactly what I was hoping for.
I do have one more suggestion on this page. The next section, "Manual defragmentation" states,
You can monitor the etcd_db_total_size_in_bytes metric to determine whether manual defragmentation is necessary.
...but does not give the reader the knowledge of how to make that determination.
On the other hand, with the success/failed log output from your other change, is this sentence even necessary? I'm not an etcd expert so I don't know myself.
@patrickstrick Thanks for taking a look! I'm glad that the new examples are helpful.
Good question about the manual defragmentation section. I'll check with the original author of that section to see if she can provide more clarity.
The 4.10 [1] docs have been updated with the new examples. The 4.11 docs [2] should be updated as soon as the cherry-pick process is complete.
[1] https://docs.openshift.com/container-platform/4.10/post_installation_configuration/cluster-tasks.html#etcd-defrag_post-install-cluster-tasks [2] https://docs.openshift.com/container-platform/4.11/post_installation_configuration/cluster-tasks.html#etcd-defrag_post-install-cluster-tasks
I'm still working with a developer to update the information about the etcd_db_total_size_in_bytes metric.
Hi @patrickstrick - After discussing the etcd_db_total_size_in_bytes metric with an SME, I updated the "Manual defragmentation" section. When you can, please take a look at this local preview (VPN required): http://file.rdu.redhat.com/lahinson/etcd-manual-defrag/post_installation_configuration/cluster-tasks.html#manual-defrag-etcd-data_post-install-cluster-tasks
@patrickstrick Please ignore my last comment. I just received more information from the SME that changes my draft. I'll let you know when it's ready for review. Thanks, and sorry for any confusion!
@patrickstrick The updated "Manual defragmentation" section is ready for review. Here's the preview link (VPN required): http://file.rdu.redhat.com/lahinson/etcd-manual-defrag/post_installation_configuration/cluster-tasks.html#etcd-defrag_post-install-cluster-tasks
I updated the first part of that section and added a "Next steps" subsection. PTAL when you can. Thanks!
Fantastic! This is much clearer (and it probably more accurate, but I'm not the expert).
I did notice one change that we didn't discuss that I want to call out in case it was accidental:
Under Procedure, step 1a now says:
oc get pods -n openshift-etcd -o wide | grep -v guard | grep etcd
The 4.11 docs match, but the 4.10 docs instead say:
oc get pods -n openshift-etcd -o wide | grep -v quorum-guard | grep etcd
Good catch @patrickstrick! I didn't update step 1a when I made my changes, so those steps must have been different for a while. I'll check with the dev team to make sure that those commands are correct.
Hi @patrickstrick - The procedures in the 4.10 and 4.11 docs are correct. I had a tester verify them this afternoon. It looks like the command had changes introduced for 4.11. In any case, I can confirm that step 1a is correct in both doc sets.
The updates are now live in the 4.10 [1] and 4.11 [2] docs.
[1] https://docs.openshift.com/container-platform/4.10/post_installation_configuration/cluster-tasks.html#etcd-defrag_post-install-cluster-tasks [2] https://docs.openshift.com/container-platform/4.11/post_installation_configuration/cluster-tasks.html#etcd-defrag_post-install-cluster-tasks
@patrickstrick If you're satisfied with the updates, can you close this issue? I don't seem to have authorization to do that. Thanks!