Merge pull request #113330 from dfitzmau/OSDOCS-16988-2

OSDOCS-16988-2: CQA PR 2 for INSTALL-1: Core Installation Concepts and Customizations

Author: bscott-rh

installing/validation_and_troubleshooting/installing-troubleshooting.adoc

@@ -6,11 +6,14 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-To assist in troubleshooting a failed {product-title} installation, you can gather logs from the bootstrap and control plane machines. You can also get debug information from the installation program. If you are unable to resolve the issue using the logs and debug information, see xref:../../support/troubleshooting/troubleshooting-installations.adoc#determining-where-installation-issues-occur_troubleshooting-installations[Determining where installation issues occur] for component-specific troubleshooting.
+[role="_abstract"]
+To assist in troubleshooting a failed {product-title} installation, you can gather logs from the bootstrap and control plane machines. You can also get debug information from the installation program.
+
+If you are unable to resolve the issue by using the logs and debug information, see "Determining where installation issues occur" in the _Additional resources_ section.
 
 [NOTE]
 ====
-If your {product-title} installation fails and the debug output or logs contain network timeouts or other connectivity errors, review the guidelines for xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configuring your firewall]. Gathering logs from your firewall and load balancer can help you diagnose network-related errors.
+If your {product-title} installation fails and the debug output or logs contain network timeouts or other connectivity errors, review the guidelines "Configuring your firewall" in the _Additional resources_ section. By gathering logs from your firewall and load balancer, you can diagnose network-related errors.
 ====
 
 == Prerequisites
@@ -23,10 +26,16 @@ include::modules/manually-gathering-logs-with-ssh.adoc[leveloffset=+1]
 
 include::modules/manually-gathering-logs-without-ssh.adoc[leveloffset=+1]
 
-include::modules/installation-getting-debug-information.adoc[leveloffset=+1]
+include::modules/installing-getting-debug-information.adoc[leveloffset=+1]
 
 include::modules/restarting-installation.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
-.Additional resources
+[id="additional-resources_installing-troubleshooting"]
+== Additional resources
+
+* xref:../../support/troubleshooting/troubleshooting-installations.adoc#determining-where-installation-issues-occur_troubleshooting-installations[Determining where installation issues occur]
+
+* xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[Configuring your firewall]
+
 * xref:../../installing/overview/index.adoc#ocp-installation-overview[Installing an {product-title} cluster]

modules/installation-bootstrap-gather.adoc

@@ -8,14 +8,11 @@
 = Gathering logs from a failed installation
 
 [role="_abstract"]
-If you gave an SSH key to your installation program, you can gather data about
-your failed installation.
+If you provided an SSH key to your installation program, you can gather data about your failed installation.
 
 [NOTE]
 ====
-You use a different command to gather logs about an unsuccessful installation
-than to gather logs from a running cluster. If you must gather logs from a
-running cluster, use the `oc adm must-gather` command.
+You use a different command to gather logs about an unsuccessful installation than to gather logs from a running cluster. If you must gather logs from a running cluster, use the `oc adm must-gather` command.
 ====
 
 .Prerequisites
@@ -26,8 +23,7 @@ running cluster, use the `oc adm must-gather` command.
 
 .Procedure
 
-. Generate the commands that are required to obtain the installation logs from
-the bootstrap and control plane machines:
+. Generate the commands that are required to obtain the installation logs from the bootstrap and control plane machines:
 +
 ** If you used installer-provisioned infrastructure, change to the directory that contains the installation program and run the following command:
 +
@@ -54,8 +50,8 @@ $ ./openshift-install gather bootstrap --dir <installation_directory> \
 where:
 +
 --
-* `installation_directory`:: Specify the same directory you specified when you ran `./openshift-install create cluster`. This directory contains the {product-title} definition files that the installation program creates.
-* `<bootstrap_address>`:: Specify the fully qualified domain name or IP address of the cluster's bootstrap machine.
+* `installation_directory`:: Specifies the same directory you specified when you ran `./openshift-install create cluster`. This directory contains the {product-title} definition files that the installation program creates.
+* `<bootstrap_address>`:: Specifies the fully qualified domain name or IP address of the cluster's bootstrap machine.
 *  `<master_*_address>`:: For each control plane, or master, machine in your cluster, replace this placeholder with its fully qualified domain name or IP address.
 +
 [NOTE]
@@ -71,5 +67,4 @@ INFO Pulling debug logs from the bootstrap machine
 INFO Bootstrap gather logs captured here "<installation_directory>/log-bundle-<timestamp>.tar.gz"
 ----
 +
-If you open a Red Hat support case about your installation failure, include
-the compressed logs in the case.
+If you open a Red Hat support case about your installation failure, include the compressed logs when opening a Red Hat support case.

modules/installation-getting-debug-information.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// *installing/installing-troubleshooting.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="installing-getting-debug-information_{context}"]
+= Getting debug information from the installation program
+
+[role="_abstract"]
+You can choose between two methods to get debug information from the installation program.
+
+.Procedure
+
+* Look at debug messages from a past installation in the hidden `.openshift_install.log` file. To do this task, enter a command similar to the following example:
++
+[source,terminal]
+----
+$ cat ~/<installation_directory>/.openshift_install.log
+----
++
+For `<installation_directory>`, specify the same directory you specified when you ran `./openshift-install create cluster`.
+
+* Change to the directory that contains the installation program and re-run the command with the `--log-level=debug` argument:
++
+[source,terminal]
+----
+$ ./openshift-install create cluster --dir <installation_directory> --log-level debug
+----
++
+For `<installation_directory>`, specify the same directory you specified when you ran `./openshift-install create cluster`.

modules/installing-getting-debug-information.adoc

@@ -4,10 +4,10 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="installation-manually-gathering-logs-with-SSH_{context}"]
-= Manually gathering logs with SSH access to your host(s)
+= Manually gathering logs with SSH access to your hosts
 
-Manually gather logs in situations where `must-gather` or automated collection
-methods do not work.
+[role="_abstract"]
+Manually gather logs in situations where `must-gather` or automated collection methods do not work.
 
 [IMPORTANT]
 ====
@@ -16,44 +16,39 @@ By default, SSH access to the {product-title} nodes is disabled on the {rh-opens
 
 .Prerequisites
 
-* You must have SSH access to your host(s).
+* You must have SSH access to your hosts.
 
 .Procedure
 
-. Collect the `bootkube.service` service logs from the bootstrap host using the
-`journalctl` command by running:
+. Collect the `bootkube.service` service logs from the bootstrap host by entering the `journalctl` command:
 +
 [source,terminal]
 ----
 $ journalctl -b -f -u bootkube.service
 ----
 
-. Collect the bootstrap host's container logs using the podman logs. This is shown
-as a loop to get all of the container logs from the host:
+. Collect the container logs of the bootstrap host by using the podman logs. Podman logs are shown as a loop to get all of the container logs from the host.
 +
 [source,terminal]
 ----
 $ for pod in $(sudo podman ps -a -q); do sudo podman logs $pod; done
 ----
 
-. Alternatively, collect the host's container logs using the `tail` command by
-running:
+. Alternatively, collect the container logs of the host by entering the `tail` command:
 +
 [source,terminal]
 ----
 # tail -f /var/lib/containers/storage/overlay-containers/*/userdata/ctr.log
 ----
 
-. Collect the `kubelet.service` and `crio.service` service logs from the master
-and worker hosts using the `journalctl` command by running:
+. Collect the `kubelet.service` and `crio.service` service logs from the control plane and compute hosts using the `journalctl` command by running:
 +
 [source,terminal]
 ----
 $ journalctl -b -f -u kubelet.service -u crio.service
 ----
 
-. Collect the master and worker host container logs using the `tail` command by
-running:
+. Collect the control plane and compute host container logs by entering the `tail` command:
 +
 [source,terminal]
 ----

modules/manually-gathering-logs-with-ssh.adoc

@@ -6,11 +6,10 @@
 [id="installation-manually-gathering-logs-without-SSH_{context}"]
 = Manually gathering logs without SSH access to your host(s)
 
-Manually gather logs in situations where `must-gather` or automated collection
-methods do not work.
+[role="_abstract"]
+Manually gather logs in situations where `must-gather` or automated collection methods do not work.
 
-If you do not have SSH access to your node, you can access the systems journal
-to investigate what is happening on your host.
+If you do not have SSH access to your node, you can access the systems journal to investigate what is happening on your host.
 
 .Prerequisites
 

modules/manually-gathering-logs-without-ssh.adoc

@@ -6,21 +6,23 @@
 [id="restarting-installation_{context}"]
 = Reinstalling the {product-title} cluster
 
+[role="_abstract"]
 If you are unable to debug and resolve issues in the failed {product-title} installation, consider installing a new {product-title} cluster. Before starting the installation process again, you must complete thorough cleanup.
-For a user-provisioned infrastructure (UPI) installation, you must manually destroy the cluster and delete all associated resources. The following procedure is for an installer-provisioned infrastructure (IPI) installation.
+
+For a user-provisioned infrastructure installation, you must manually destroy the cluster and delete all associated resources. The following procedure is for an installer-provisioned infrastructure installation.
 
 .Procedure
 
 . Destroy the cluster and remove all the resources associated with the cluster, including the hidden installer state files in the installation directory:
 +
 [source,terminal]
 ----
-$ ./openshift-install destroy cluster --dir <installation_directory> <1>
+$ ./openshift-install destroy cluster --dir <installation_directory>
 ----
-<1> `installation_directory` is the directory you specified when you ran `./openshift-install create cluster`. This directory contains the {product-title}
-definition files that the installation program creates.
++
+Where `<installation_directory>` is the directory you specified when you ran `./openshift-install create cluster`. This directory contains the {product-title} definition files that the installation program creates.
 
-. Before reinstalling the cluster, delete the installation directory:
+. Before reinstalling the cluster, delete the installation directory by running a command similar to the following command:
 +
 [source,terminal]
 ----