CNV-2386: must-gather tool

_topic_map.yml

@@ -1043,6 +1043,8 @@ Topics:
     File: cnv-events
   - Name: OpenShift cluster monitoring, logging, and Telemetry
     File: cnv-openshift-cluster-monitoring
+  - Name: Collecting container-native virtualization data for Red Hat Support
+    File: cnv-collecting-cnv-data
 - Name: Container-native Virtualization 2.0 release notes
   Dir: cnv_release_notes
   Topics:

cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc

@@ -0,0 +1,22 @@
+[id="cnv-collecting-cnv-data"]
+= Collecting {CNVProductName} data for Red Hat Support
+include::modules/cnv-document-attributes.adoc[]
+:context: cnv-collecting-cnv-data
+toc::[]
+
+
+The `must-gather` tool enables you to collect diagnostic information about your
+{product-title} cluster, including virtual machines and other data related to
+{CNVProductName}.
+
+:FeatureName: {CNVProductNameStart}
+
+include::modules/technology-preview.adoc[leveloffset=+1]
+
+include::modules/about-must-gather.adoc[leveloffset=+1]
+
+include::modules/cnv-about-collecting-cnv-data.adoc[leveloffset=+1]
+
+include::modules/gathering-data-specific-features.adoc[leveloffset=+1]
+
+

modules/about-must-gather.adoc

@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//
+// * cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc
+// * support/gathering-cluster-data.adoc
+
+[id="about-must-gather_{context}"]
+= About the must-gather tool
+
+When opening a support case, it is often helpful to provide debugging
+information about your cluster to Red Hat Support. You can gather this
+information by using the `oc adm must-gather` CLI command.
+
+The `oc adm must-gather` CLI command collects the information from your cluster
+that is most likely needed for debugging issues, such as:
+
+* Resource definitions
+* Audit logs
+* Service logs
+
+You can specify one or more images when you run the command by including the
+`--image` argument. When you specify an image, the tool collects data related to
+that feature or product.
+
+When you run `oc adm must-gather`, a new Pod is created on the cluster. The data
+is collected on that Pod and saved in a new directory that starts with
+`must-gather.local`. This directory is created in the current working
+directory.
+
+// todo: table or ref module listing available images?

modules/cnv-about-collecting-cnv-data.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc
+
+[id="cnv-about-collecting-cnv-data_{context}"]
+= About collecting {CNVProductName} data
+
+You can use the `oc adm must-gather` CLI command to collect information about your
+cluster, including features and objects associated with {CNVProductName}:
+
+* The Hyperconverged Cluster Operator namespaces (and child objects)
+* All namespaces (and their child objects) that belong to any {CNVProductName}
+resources
+* All {CNVProductName} Custom Resource Definitions (CRDs)
+* All namespaces that contain virtual machines
+* All virtual machine definitions
+
+To collect {CNVProductName} data with `must-gather`, you must specify the
+{CNVProductName} image:
+`--image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8`.

modules/gathering-data-specific-features.adoc

@@ -0,0 +1,47 @@
+// Module included in the following assemblies:
+//
+// * support/gathering-cluster-data.adoc
+// * cnv/cnv_users_guide/cnv-collecting-cnv-data.adoc
+// Dependency: modules/cnv-document-attributes.adoc
+
+[id="gathering-data-specific-features_{context}"]
+= Gathering data about specific features
+
+You can gather debugging information about specific features by using the
+`oc adm must-gather` CLI command with the `--image` or `--image-stream` argument.
+The `must-gather` tool supports multiple images, so you can gather data about
+more than one feature by running a single command.
+
+.Prerequisites
+
+* Access to the cluster as a user with the `cluster-admin` role.
+* The {product-title} CLI (`oc`) installed.
+
+.Procedure
+
+. Navigate to the directory where you want to store the `must-gather` data.
+
+. Run the `oc adm must-gather` command with one or more `--image` or `--image-stream`
+arguments. For example, the following command gathers both the default cluster
+data and information specific to {CNVProductName}:
++
+----
+$ oc adm must-gather \
+ --image-stream=openshift/must-gather \ <1>
+ --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8 <2>
+----
+<1> Default {product-title} must-gather image
+<2> {CNVProductNameStart} must-gather image
+
+. Create a compressed file from the `must-gather` directory that was just created
+in your working directory. For example, on a computer that uses a Linux
+operating system, run the following command:
++
+----
+$ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ <1>
+----
+<1> Make sure to replace `must-gather-local.5421342344627712289/` with the
+actual directory name.
+
+. Attach the compressed file to your support case on the
+link:https://access.redhat.com[Red Hat Customer Portal].

modules/support-gather-data.adoc

@@ -5,39 +5,33 @@
 [id="support_gathering_data_{context}"]
 = Gathering data about your cluster for Red Hat Support
 
-When opening a support case, it is often helpful to provide debugging
-information about your cluster to Red Hat Support. You can gather this
-information by using the `oc adm must-gather` CLI command.
-
-The `oc adm must-gather` CLI command collects the information from your cluster
-that is most likely needed for debugging issues, such as:
-
-* Resource definitions
-* Audit logs
-* Service logs
+You can gather debugging information about your cluster by using the
+`oc adm must-gather` CLI command.
 
 .Prerequisites
 
 * Access to the cluster as a user with the `cluster-admin` role.
+* The {product-title} CLI (`oc`) installed.
 
 .Procedure
 
+. Navigate to the directory where you want to store the `must-gather` data.
+
 . Run the `oc adm must-gather` command:
 +
 ----
 $ oc adm must-gather
 ----
-+
-This creates a Pod on the cluster to perform the data collection on. All of the
-collected resources and data from your cluster are saved in the current
-directory in a new directory that starts with `must-gather.local`.
 
-. Create a compressed file from the `must-gather` directory. For example, on a
-computer that uses a Linux operating system, run the following command:
+. Create a compressed file from the `must-gather` directory that was just created
+in your working directory. For example, on a computer that uses a Linux
+operating system, run the following command:
 +
 ----
-$ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/
+$ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ <1>
 ----
+<1> Make sure to replace `must-gather-local.5421342344627712289/` with the
+actual directory name.
 
 . Attach the compressed file to your support case on the
-link:http://access.redhat.com[Red Hat Customer Portal].
+link:https://access.redhat.com[Red Hat Customer Portal].

support/gathering-cluster-data.adoc

@@ -6,4 +6,5 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 // Gathering data about your cluster for Red Hat Support
+include::modules/about-must-gather.adoc[leveloffset=+1]
 include::modules/support-gather-data.adoc[leveloffset=+1]