From d7e02486d926a75d397e5a2f49e1f74436012e7b Mon Sep 17 00:00:00 2001 From: Audrey Spaulding Date: Tue, 13 Jun 2023 11:50:12 -0400 Subject: [PATCH] CNV-29398_2 --- modules/virt-must-gather-options.adoc | 54 ++++++++++++--------- modules/virt-using-virt-must-gather.adoc | 5 +- virt/support/virt-collecting-virt-data.adoc | 2 +- 3 files changed, 34 insertions(+), 27 deletions(-) diff --git a/modules/virt-must-gather-options.adoc b/modules/virt-must-gather-options.adoc index 11ee4283d6..f364702fad 100644 --- a/modules/virt-must-gather-options.adoc +++ b/modules/virt-must-gather-options.adoc @@ -10,7 +10,7 @@ You can specify a combination of scripts and environment variables for the follo * Collecting detailed virtual machine (VM) information from a namespace * Collecting detailed information about specified VMs -* Collecting image and image stream information +* Collecting image, image-stream, and image-stream-tags information * Limiting the maximum number of parallel processes used by the `must-gather` tool [id="parameters"] @@ -33,13 +33,13 @@ Using too many parallel processes can cause performance issues. Increasing the m .Scripts -Each script is only compatible with certain environment variable combinations. +Each script is compatible only with certain environment variable combinations. -`gather_vms_details`:: Collect VM 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 environment variables, but you must specify a namespace if you use the `VM` variable. +`/usr/bin/gather`:: Use the default `must-gather` script, which collects cluster data from all namespaces and includes only basic VM information. This script is compatible only with the `PROS` 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. +`/usr/bin/gather --vms_details`:: Collect VM log files, VM definitions, control-plane logs, and namespaces that belong to {VirtProductName} resources. Specifying namespaces includes their child objects. 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 environment variables, but you must specify a namespace if you use the `VM` variable. -`gather_images`:: Collect image and image stream custom resource information. This script is only compatible with the `PROS` variable. +`/usr/bin/gather --images`:: Collect image, image-stream, and image-stream-tags custom resource information. This script is compatible only with the `PROS` variable. [id="usage-and-examples_{context}"] == Usage and examples @@ -50,21 +50,24 @@ Environment variables are optional. You can run a script by itself or with one o .Compatible parameters |=== |Script |Compatible environment variable -|`gather_vms_details` +|`/usr/bin/gather` |* `PROS=` +|`/usr/bin/gather --vms_details` |* For a namespace: `NS=` * For a VM: `VM= NS=` * `PROS=` -|`gather` |* `PROS=` -|`gather_images` |* `PROS=` + +|`/usr/bin/gather --images` |* `PROS=` |=== -To customize the data that `must-gather` collects, you append a double dash (`--`) to the command, followed by a space and one or more compatible parameters. + .Syntax + + [source,terminal,subs="attributes+"] ---- $ oc adm must-gather \ @@ -72,6 +75,19 @@ $ oc adm must-gather \ -- ---- +.Default data collection parallel processes + +By default, five processes run in parallel. + +[source,terminal,subs="attributes+"] +---- +$ oc adm must-gather \ + --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ + -- PROS=5 /usr/bin/gather <1> +---- +<1> You can modify the number of parallel processes by changing the default. + + .Detailed VM information The following command collects detailed VM information for the `my-vm` VM in the `mynamespace` namespace: @@ -80,28 +96,18 @@ The following command collects detailed VM information for the `my-vm` VM in the ---- $ oc adm must-gather \ --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ - -- NS=mynamespace VM=my-vm gather_vms_details <1> + -- NS=mynamespace VM=my-vm /usr/bin/gather --vms_details <1> ---- <1> The `NS` environment variable is mandatory if you use the `VM` environment variable. -.Default data collection limited to three parallel processes -The following command collects default `must-gather` information by using a maximum of three parallel processes: +.Image, image-stream, and image-stream-tags information + +The following command collects image, image-stream, and image-stream-tags information from the cluster: [source,terminal,subs="attributes+"] ---- $ oc adm must-gather \ --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ - -- PROS=3 gather ----- - -.Image and image stream information - -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-rhel9:v{HCOVersion} \ - -- gather_images + /usr/bin/gather --images ---- diff --git a/modules/virt-using-virt-must-gather.adoc b/modules/virt-using-virt-must-gather.adoc index 6c24365f38..be62ea99c5 100644 --- a/modules/virt-using-virt-must-gather.adoc +++ b/modules/virt-using-virt-must-gather.adoc @@ -23,6 +23,7 @@ The default data collection includes information about the following resources: + [source,terminal,subs="attributes+"] ---- -$ oc adm must-gather --image-stream=openshift/must-gather \ - --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} +$ oc adm must-gather + --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ + -- /usr/bin/gather ---- \ No newline at end of file diff --git a/virt/support/virt-collecting-virt-data.adoc b/virt/support/virt-collecting-virt-data.adoc index 2f28b87620..89fb08bf8d 100644 --- a/virt/support/virt-collecting-virt-data.adoc +++ b/virt/support/virt-collecting-virt-data.adoc @@ -54,7 +54,7 @@ Collecting data about malfunctioning virtual machines (VMs) minimizes the time r .Procedure -. xref:../../virt/support/virt-collecting-virt-data.adoc#virt-must-gather-options_virt-collecting-virt-data[Collect must-gather data for the VMs] using the `gather_vms_details` script. +. xref:../../virt/support/virt-collecting-virt-data.adoc#virt-must-gather-options_virt-collecting-virt-data[Collect must-gather data for the VMs] using the `/usr/bin/gather` script. . Collect screenshots of VMs that have crashed _before_ you restart them. . xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#vm-memory-dump-commands_virt-using-the-cli-tools[Collect memory dumps from VMs] _before_ remediation attempts. . Record factors that the malfunctioning VMs have in common. For example, the VMs have the same host or network.