From 324ce4a237672ad1ad13728b327c413ce0f334bc Mon Sep 17 00:00:00 2001 From: Miriam Weiss Date: Thu, 13 Nov 2025 09:35:58 +0200 Subject: [PATCH] CNV-66694: Split for DITA compatability --- modules/virt-must-gather-options.adoc | 92 ++++-------------------- modules/virt-using-virt-must-gather.adoc | 54 +++++++++++++- 2 files changed, 67 insertions(+), 79 deletions(-) diff --git a/modules/virt-must-gather-options.adoc b/modules/virt-must-gather-options.adoc index 642a43c198..5ae2dd324d 100644 --- a/modules/virt-must-gather-options.adoc +++ b/modules/virt-must-gather-options.adoc @@ -7,20 +7,18 @@ = must-gather tool options [role="_abstract"] -You can run the `oc adm must-gather` command to collect `must gather` images for all the Operators and products deployed on your cluster without the need to explicitly specify the required images. +You can add optional parameters to the `must-gather` command to collect additional information beyond what `must-gather` collects by default. -Alternatively, you can specify a combination of scripts and environment variables for the following options: +You can specify a combination of scripts and environment variables for the following options: * Collecting detailed virtual machine (VM) information from a namespace * Collecting detailed information about specified VMs * Collecting image, image-stream, and image-stream-tags information * Limiting the maximum number of parallel processes used by the `must-gather` tool -[id="parameters"] -== Parameters +[id="must-gather-environment-variables_{context}"] +== Environment variables -Environment variables:: -+ You can specify environment variables for a compatible script. `NS=`::: Collect virtual machine information, including `virt-launcher` pod details, from the namespace that you specify. The `VirtualMachine` and `VirtualMachineInstance` CR data is collected for all namespaces. @@ -34,8 +32,9 @@ You can specify environment variables for a compatible script. Using too many parallel processes can cause performance issues. Increasing the maximum number of parallel processes is not recommended. ==== -Scripts:: -+ +[id="must-gather-scripts_{context}"] +== Scripts + Each script is compatible only with certain environment variable combinations. `/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. @@ -49,8 +48,15 @@ Each script is compatible only with certain environment variable combinations. [id="usage-and-examples_{context}"] == Usage and examples -Environment variables are optional. You can run a script by itself or with one or more compatible environment variables. +You can run a script by itself or with one or more compatible environment variables. +.must-gather syntax with optional parameters +[source,terminal,subs="attributes+"] +---- +$ oc adm must-gather \ + --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ + -- +---- .Compatible parameters [options="header"] @@ -68,71 +74,3 @@ Environment variables are optional. You can run a script by itself or with one o |`/usr/bin/gather --images` |* `PROS=` |=== - - - -Syntax:: -+ -To collect `must-gather` logs for all Operators and products on your cluster in a single pass, run the following command: -+ -[source,terminal,subs="attributes+"] ----- -$ oc adm must-gather --all-images ----- -+ -If you need to pass additional parameters to individual `must-gather` images, use the following command: -+ -[source,terminal,subs="attributes+"] ----- -$ oc adm must-gather \ - --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ - -- ----- - -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: -+ -[source,terminal,subs="attributes+"] ----- -$ oc adm must-gather \ - --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ - -- 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. - - -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} \ - /usr/bin/gather --images ----- - -Instance types information:: -+ -The following command collects instance types 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} \ - /usr/bin/gather --instancetypes ----- diff --git a/modules/virt-using-virt-must-gather.adoc b/modules/virt-using-virt-must-gather.adoc index 002c1f6c7c..4c1e962d7f 100644 --- a/modules/virt-using-virt-must-gather.adoc +++ b/modules/virt-using-virt-must-gather.adoc @@ -18,7 +18,7 @@ The default data collection includes information about the following resources: * Namespaces that contain virtual machines * Basic virtual machine definitions -Instance types information is not currently collected by default; you can, however, run a command to optionally collect it. +You can add optional environment details and scripts to the `must-gather` command to collect additional information. Use these environment variables and scripts to collect data about specific VMs, images, or instance types. .Prerequisites @@ -26,7 +26,7 @@ Instance types information is not currently collected by default; you can, howev .Procedure -* Run the following command to collect data about {VirtProductName}: +* Run the `must-gather` command to collect data about {VirtProductName}: + [source,terminal,subs="attributes+"] ---- @@ -34,3 +34,53 @@ $ oc adm must-gather \ --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ -- /usr/bin/gather ---- ++ +[NOTE] +==== +You can also collect `must-gather` logs for all Operators and products on your cluster by running following command: + +[source,terminal,subs="attributes+"] +---- +$ oc adm must-gather --all-images +---- +==== + +.. Run the following command to modify the number of processes running in parallel when collecting `must-gather` data: ++ +[source,terminal,subs="attributes+"] +---- +$ oc adm must-gather \ + --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ + -- PROS= /usr/bin/gather +---- ++ +`PROS` defines the number of parallel processes running to collect data. The default number of processes is 5. Increasing the number of processes may result in faster data collection, but uses more resources. Increasing the maximum number of parallel processes is not recommended. + +.. Run the following command to collect detailed information for a specific VM in a specific namespace: ++ +[source,terminal,subs="attributes+"] +---- +$ oc adm must-gather \ + --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ + -- NS= VM= /usr/bin/gather --vms_details +---- ++ +`NS` is the environment variable for `namespace`. It is mandatory when using the `VM` environment variable. + +.. Run the following command to collect 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} \ + /usr/bin/gather --images +---- + +.. Run the following command to collect information about instance types from the cluster: ++ +[source,terminal,subs="attributes+"] +---- +$ oc adm must-gather \ + --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} \ + /usr/bin/gather --instancetypes +----