Merge pull request #10983 from bfallonf/diag_edits

Edits after #8644

Author: Brice Fallon-Freeman

admin_guide/diagnostics_tool.adoc

@@ -31,17 +31,16 @@ connected to.
 [[admin-guide-using-the-diagnostics-tool]]
 == Using the Diagnostics Tool
 
-{product-title} can be deployed in several ways. These include:
+You can deploy {product-title} in several ways. These include:
 
 * Built from source
-* Included in a VM image
+* Included within a VM image
 * As a container image
-* As enterprise RPMs
+* Using enterprise RPMs
 
-Each method implies a different configuration and environment. To minimize
-environment assumptions, diagnostics are included with the `openshift`
-binary to provide the ability to run the diagnostics tool within an
-{product-title} server or client.
+Each method is suited for a different configuration and environment. To minimize
+environment assumptions, the diagnostics tool is included with the `openshift`
+binary to provide diagnostics within an {product-title} server or client.
 
 To use the diagnostics tool, preferably on a master host and as cluster
 administrator, run:
@@ -50,7 +49,7 @@ administrator, run:
 # oc adm diagnostics
 ----
 
-This runs all available diagnostics, skipping any that do not apply.
+This runs all available diagnostics and skips any that do not apply to the environment.
 
 You can run a specific diagnostics by name or run specific
 diagnostics by name as you work to address issues. For example:
@@ -63,8 +62,7 @@ The options for the diagnostics tool require working configuration files. For
 example, the *NodeConfigCheck* does not run unless a node configuration is
 available.
 
-The diagnostics tool verifies that the configuration files reside in their
-standard locations:
+The diagnostics tool uses the standard configuration file locations by default:
 
 * Client:
 ** As indicated by the `$KUBECONFIG` environment variable
@@ -147,14 +145,14 @@ If there are any errors, this diagnostic stores results and retrieved files in a
 [[admin-guide-diagnostics-tool-server-environment]]
 == Running Diagnostics in a Server Environment
 
-Master and node diagnostics are most useful in an Ansible-deployed cluster. This
-provides some diagnostic benefits:
+An Ansible-deployed cluster provides additional diagnostic benefits for 
+nodes within an {product-title} cluster. These include:
 
 * Master and node configuration is based on a configuration file in a standard
 location.
 * Systemd units are configured to manage the server(s).
 * Both master and node configuration files are in standard locations.
-* Systemd units are created and configured for managing the nodes in a cluster
+* Systemd units are created and configured for managing the nodes in a cluster.
 * All components log to journald.
 
 Keeping to the default location of the configuration files placed by an
@@ -175,21 +173,19 @@ run.
 [[admin-guide-diagnostics-tool-client-environment]]
 == Running Diagnostics in a Client Environment
 
-You can access the diagnostics tool as an ordinary user, as a *cluster-admin*
-user, and can run on a host where {product-title} master or node servers are
-operating. The diagnostics attempt to use as much access as the user has
-available.
+You can run the diagnostics tool as an ordinary user or a `cluster-admin`, and
+it runs using the level of permissions granted to the  account from which you
+run it.
 
-A client with ordinary access should be able to diagnose its connection
-to the master and run a diagnostic pod. If multiple users or masters are
-configured, connections are tested for all, but the diagnostic pod
-only runs against the current user, server, or project.
+A client with ordinary access can diagnose its connection to the master and run
+a diagnostic pod. If multiple users or masters are configured, connections are
+tested for all, but the diagnostic pod only runs against the current user,
+server, or project.
 
-A client with *cluster-admin* access available (for any user, but only the
-current master) can diagnose the status of infrastructure such as nodes,
-registry, and router. In each case, running `oc adm diagnostics` searches for
-the standard client configuration file in its standard location and uses it if
-available.
+A client with `cluster-admin` access can diagnose the status of infrastructure
+such as nodes, registry, and router. In each case, running `oc adm diagnostics`
+searches for the standard client configuration file in its standard location and
+uses it if available.
 
 [[ansible-based-tooling-health-checks]]
 == Ansible-based Health Checks
@@ -228,14 +224,14 @@ using the provided *_health.yml_* playbook.
 [WARNING]
 ====
 Due to potential changes the health check playbooks can make to the environment,
-you must run the playbooks against only clusters that were deployed using
-Ansible and using the same inventory file that used during deployment. The
-changes consist of installing dependencies so that the checks can gather the
-required information. In some circumstances, additional system components, such
-as `docker` or networking configurations, can be altered if their current state
-differs from the configuration in the inventory file. You should run these
-health checks only if you do not expect the inventory file to make any changes
-to the existing cluster configuration. 
+you must run the playbooks against only Ansible-deployed clusters and using the
+same inventory file used for deployment. The changes consist of installing
+dependencies so that the checks can gather the required information. In some
+circumstances, additional system components, such as `docker` or networking
+configurations, can change if their current state differs from the configuration
+in the inventory file. You should run these health checks only if you do not
+expect the inventory file to make any changes to the existing cluster
+configuration. 
 ====
 
 [[admin-guide-diagnostics-tool-ansible-checks]]
@@ -282,7 +278,7 @@ installations). Checks that *docker*'s total usage does not exceed a
 user-defined limit. If no user-defined limit is set, *docker*'s maximum usage
 threshold defaults to 90% of the total size available.
 
-The threshold limit for total percent usage can be set with a variable in the
+You can set the threshold limit for total percent usage with a variable in the
 inventory file, for example `max_thinpool_data_usage_percent=90`.
 
 This also checks that *docker*'s storage is using a
@@ -378,8 +374,7 @@ ifdef::openshift-origin[]
 endif::[]
 image via the Docker CLI.
 
-As a non-root user that has privileges to run containers specify the cluster's
-inventory file and the *_health.yml_* playbook:
+Run the following as a non-root user that has privileges to run containers:
 
 ----
 # docker run -u `id -u` \ <1>
@@ -408,9 +403,9 @@ used according to the `INVENTORY_FILE` environment variable in the container.
 inside the container.
 <5> Set any variables desired for a single run with the `-e key=value` format.
 
-In the above command, the SSH key is mounted with the `:Z` flag so that the
-container can read the SSH key from its restricted SELinux context; this means
-that your original SSH key file will be relabeled to something like
+In the previous command, the SSH key is mounted with the `:Z` option so that the
+container can read the SSH key from its restricted SELinux context. Adding this
+option means that your original SSH key file is relabeled similarly to
 `system_u:object_r:container_file_t:s0:c113,c247`. For more details about `:Z`,
 see the `docker-run(1)` man page.
 
@@ -422,9 +417,9 @@ becomes unable to access the public keys to allow remote login. To avoid
 altering the original file labels, mount a copy of the SSH key or directory.
 ====
 
-You might mount an entire *_.ssh_* directory for various reasons. For example,
-this would allow you to use an SSH configuration to match keys with hosts or
-modify other connection parameters. It could also allow a user to provide a
-*_known_hosts_* file and have SSH validate host keys, which is disabled by the
-default configuration and can be re-enabled with an environment variable by
-adding `-e ANSIBLE_HOST_KEY_CHECKING=True` to the `docker` command line.
+Mounting an entire *_.ssh_* directory can be helpful for:
+
+* Allowing you to use an SSH configuration to match keys with hosts or
+modify other connection parameters.
+* Allowing a user to provide a *_known_hosts_* file and have SSH validate host keys. This is disabled by the default configuration and can be re-enabled with an environment variable by adding `-e ANSIBLE_HOST_KEY_CHECKING=True` to the `docker` command line.
+