Merge pull request #28425 from mikemckiernan/toolbox

feat: doc enhancements for toolbox (OSDOCS-1508)

Author: codyhoag

modules/about-toolbox.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * support/gathering-cluster-data.adoc
+
+[id="about-toolbox_{context}"]
+= About `toolbox`
+
+`toolbox` is a tool that starts a container on a {op-system-first} system. The tool is primarily used to start a container that includes the required binaries and plug-ins that are needed to run commands such as `sosreport` and `redhat-support-tool`.
+
+The primary purpose for a `toolbox` container is to gather diagnostic information and to provide it to Red Hat Support. However, if additional diagnostic tools are required, you can add RPM packages or run an image that is an alternative to the standard support tools image.

modules/support-installing-packages-to-a-toolbox-container.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * support/gathering-cluster-data.adoc
+
+[id="installing-packages-to-a-toolbox-container_{context}"]
+= Installing packages to a `toolbox` container
+
+By default, running the `toolbox` command starts a container with the `registry.redhat.io/rhel8/support-tools:latest` image. This image contains the most frequently used support tools. If you need to collect node-specific data that requires a support tool that is not part of the image, you can install additional packages.
+
+.Prerequisites
+
+* You have accessed a node with the `oc debug node/<node_name>` command.
+
+.Procedure
+
+. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths:
++
+[source,terminal]
+----
+# chroot /host
+----
+
+. Start the toolbox container:
++
+[source,terminal]
+----
+# toolbox
+----
+
+. Install the additional package, such as `wget`:
++
+[source,terminal]
+----
+# dnf install -y <package_name>
+----

modules/support-starting-an-alternative-image-with-toolbox.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * support/gathering-cluster-data.adoc
+
+[id="starting-an-alternative-image-with-toolbox_{context}"]
+= Starting an alternative image with `toolbox`
+
+By default, running the `toolbox` command starts a container with the `registry.redhat.io/rhel8/support-tools:latest` image. You can start an alternative image by creating a `.toolboxrc` file and specifying the image to run.
+
+.Prerequisites
+
+* You have accessed a node with the `oc debug node/<node_name>` command.
+
+.Procedure
+
+. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths:
++
+[source,terminal]
+----
+# chroot /host
+----
+
+. Create a `.toolboxrc` file in the home directory for the root user ID:
++
+[source,terminal]
+----
+# vi ~/.toolboxrc
+----
++
+[source,text]
+----
+REGISTRY=quay.io                <.>
+IMAGE=fedora/fedora:33-x86_64   <.>
+TOOLBOX_NAME=toolbox-fedora-33  <.>
+----
+<.> Optional: Specify an alternative container registry.
+<.> Specify an alternative image to start.
+<.> Optional: Specify an alternative name for the toolbox container.
+
+. Start a toolbox container with the alternative image:
++
+[source,terminal]
+----
+# toolbox
+----
++
+[NOTE]
+====
+If an existing `toolbox` pod is already running, the `toolbox` command outputs `'toolbox-' already exists. Trying to start...`. Remove the running toolbox container with `podman rm toolbox-` and spawn a new toolbox container, to avoid issues with `sosreport` plug-ins.
+====

support/gathering-cluster-data.adoc

@@ -43,3 +43,14 @@ include::modules/support-collecting-network-trace.adoc[leveloffset=+1]
 
 // Providing diagnostic data to Red Hat Support
 include::modules/support-providing-diagnostic-data-to-red-hat.adoc[leveloffset=+1]
+
+// About `toolbox`
+include::modules/about-toolbox.adoc[leveloffset=+1]
+
+// Installing packages to a toolbox container
+[discrete]
+include::modules/support-installing-packages-to-a-toolbox-container.adoc[leveloffset=+2]
+
+// Starting an alternative image with toolbox
+[discrete]
+include::modules/support-starting-an-alternative-image-with-toolbox.adoc[leveloffset=+2]