Merge pull request #38786 from ousleyp/must-gather-changes

[virt] must-gather changes for 4.9.1/4.8.4

Author: ousleyp

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

@@ -10,12 +10,10 @@
 You can use the `oc adm must-gather` CLI command to collect information about your
 cluster, including features and objects associated with {VirtProductName}:
 
-* The Hyperconverged Cluster Operator namespaces (and child objects)
-* All namespaces (and their child objects) that belong to any {VirtProductName}
-resources
+* The {VirtProductName} Operator namespaces (and child objects)
 * All {VirtProductName} custom resource definitions (CRDs)
 * All namespaces that contain virtual machines
-* All virtual machine definitions
+* Basic virtual machine definitions
 
 To collect {VirtProductName} data with `must-gather`, you must specify the
 {VirtProductName} image:

modules/virt-must-gather-usage-targeted-vm-data.adoc

@@ -0,0 +1,82 @@
+// Module included in the following assemblies:
+//
+// * virt/logging_events_monitoring/virt-collecting-virt-data.adoc
+
+[id="virt-must-gather-usage-targeted-vm-data_{context}"]
+= must-gather tool usage for targeted VM data
+
+When you use the `must-gather` CLI tool to collect {VirtProductName} data, the virtual machine (VM) information collected by default is limited to `VirtualMachine` and `VirtualMachineInstance` custom resources (CRs). You can request additional or targeted data by including parameters when you run the `must-gather` command. These parameters include environment variables and scripts.
+
+[discrete]
+[id="supported-parameters_{context}"]
+=== Supported parameters
+
+.Environment variables
+
+`NS=<namespace_name>`:: Gather virtual machine details from the namespace that you specify.
+
+`VM=<vm_name>`:: Gather details about a particular virtual machine. To use this option, you must also specify a namespace by using the `NS` environment variable.
+
+`PROS=<number_of_processes>`:: Modify the maximum number of parallel processes that the `must-gather` tool uses. By default, the tool uses no more than five parallel processes.
++
+[IMPORTANT]
+====
+Using too many parallel processes can cause performance issues. Increasing the maximum number of parallel processes is not recommended.
+====
+
+.Scripts
+
+Each script is only compatible with certain variable combinations.
+
+`gather_vms_details`:: Collect virtual machine log files, VM definitions, and namespaces (and their child objects) that belong to {VirtProductName} resources. If you use this parameter without specifying a namespace or VM, the `must-gather` tool collects this data for all VMs in the cluster. This script is compatible with all of the supported environment variables, but you must specify a namespace if you use the `VM` variable.
+
+`gather`:: Use the default `must-gather` script, which collects cluster data from all namespaces and includes only basic VM information. This script is only compatible with the `PROS` variable.
+
+`gather_images`:: Collect image and image stream custom resource information. This script is only compatible with the `PROS` variable.
+
+[discrete]
+[id="usage_{context}"]
+=== Usage
+
+To customize the data that `must-gather` collects, append a double dash (`--`) to the command, followed by one or more compatible parameters. If you use any environment variables, you must specify a script.
+
+The following options are valid:
+
+* You can specify one script without using any environment variables.
+* You can use one or more environment variables in any order, followed by one script.
+
+.Syntax
+
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion} \
+ -- <environment_variable_1> <environment_variable_2> <script_name>
+----
+
+.Examples
+
+* The following command collects extensive VM details for the `my-vm` VM in the `mynamespace` namespace:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion} -- NS=mynamespace VM=my-vm gather_vms_details
+----
++
+[IMPORTANT]
+====
+If you use the `VM` environment variable, you must also specify a namespace.
+====
+
+* The following command collects default `must-gather` information by using a maximum of three parallel processes:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion} -- PROS=3 gather
+----
+
+* The following command collects image and image stream information from the cluster:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion} -- gather_images
+----

virt/logging_events_monitoring/virt-collecting-virt-data.adoc

@@ -20,3 +20,5 @@ include::modules/about-must-gather.adoc[leveloffset=+1]
 include::modules/virt-about-collecting-virt-data.adoc[leveloffset=+1]
 
 include::modules/gathering-data-specific-features.adoc[leveloffset=+1]
+
+include::modules/virt-must-gather-usage-targeted-vm-data.adoc[leveloffset=+1]