diff --git a/admin_guide/diagnostics_tool.adoc b/admin_guide/diagnostics_tool.adoc index 41df2cffd789..60a12f2569d3 100644 --- a/admin_guide/diagnostics_tool.adoc +++ b/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. +