Merge pull request #49682 from openshift/revert-49141-CNV-15574-troubleshooting-guide

Revert "CNV-15574: troubleshooting guide"

Author: apinnick

_topic_maps/_topic_map.yml

@@ -3456,7 +3456,7 @@ Topics:
     File: virt-exposing-custom-metrics-for-vms
   - Name: OpenShift Virtualization critical alerts
     File: virt-virtualization-alerts
-  - Name: Collecting data for Red Hat Support
+  - Name: Collecting OpenShift Virtualization data for Red Hat Support
     File: virt-collecting-virt-data
     Distros: openshift-enterprise
 - Name: Backup and restore

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

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * virt/logging_events_monitoring/virt-collecting-virt-data.adoc
+
+//This file contains UI elements and/or package names that need to be updated.
+
+:_content-type: CONCEPT
+[id="virt-about-collecting-virt-data_{context}"]
+= About collecting {VirtProductName} data
+
+You can use the `oc adm must-gather` CLI command to collect information about your
+cluster, including features and objects associated with {VirtProductName}:
+
+* The {VirtProductName} Operator namespaces (and child objects)
+* All {VirtProductName} custom resource definitions (CRDs)
+* All namespaces that contain virtual machines
+* Basic virtual machine definitions
+
+To collect {VirtProductName} data with `must-gather`, you must specify the
+{VirtProductName} image:
+`--image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion}`.

modules/virt-collecting-data-about-vms.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 information, including `virt-launcher` pod details, from the namespace that you specify. The `VirtualMachine` and `VirtualMachineInstance` CR data is collected for all namespaces.
+
+`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
+----

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

@@ -1,50 +1,25 @@
 :_content-type: ASSEMBLY
 include::_attributes/common-attributes.adoc[]
 [id="virt-collecting-virt-data"]
-= Collecting data for Red Hat Support
+= Collecting {VirtProductName} data for Red Hat Support
 :context: virt-collecting-virt-data
 
 toc::[]
 
-When you submit a xref:../../support/getting-support.adoc#support-submitting-a-case_getting-support[support case] to Red Hat Support, it is helpful to provide debugging information for {product-title} and {VirtProductName} by using the following tools:
+When opening a support case, it is helpful to provide debugging
+information about your cluster to Red Hat Support.
 
-must-gather tool::
-The `must-gather` tool collects diagnostic information, including resource definitions and service logs.
+The `must-gather` tool enables you to collect diagnostic information about your
+{product-title} cluster, including virtual machines and other data related to
+{VirtProductName}.
 
-Prometheus::
-Prometheus is a time-series database and a rule evaluation engine for metrics. Prometheus sends alerts to Alertmanager for processing.
+For prompt support, supply diagnostic information for both {product-title}
+and {VirtProductName}.
 
-Alertmanager::
-The Alertmanager service handles alerts received from Prometheus. The Alertmanager is also responsible for sending the alerts to external notification systems.
+include::modules/about-must-gather.adoc[leveloffset=+1]
 
-include::modules/virt-collecting-data-about-your-environment.adoc[leveloffset=+1]
+include::modules/virt-about-collecting-virt-data.adoc[leveloffset=+1]
 
-[id="additional-resources_collecting-data-about-your-environment"]
-[role="_additional-resources"]
-=== Additional resources
-* Configuring the xref:../../monitoring/configuring-the-monitoring-stack.adoc#modifying-retention-time-for-prometheus-metrics-data_configuring-the-monitoring-stack[retention time] for Prometheus metrics data
-* Configuring the Alertmanager to send xref:../../monitoring/managing-alerts.adoc#sending-notifications-to-external-systems_managing-alerts[alert notifications] to external systems
-* Collecting `must-gather` data for xref:../../support/gathering-cluster-data.adoc#support_gathering_data_gathering-cluster-data[{product-title}]
-* Collecting `must-gather` data for link:https://access.redhat.com/documentation/en-us/red_hat_openshift_data_foundation/4.10/html-single/troubleshooting_openshift_data_foundation/index#downloading-log-files-and-diagnostic-information_rhodf[{rh-storage-first}].
-* Collecting `must-gather` data for xref:../../virt/logging_events_monitoring/virt-collecting-virt-data.adoc#virt-using-virt-must-gather_virt-collecting-virt-data[{VirtProductName}]
-* Collecting Prometheus metrics for xref:../../monitoring/managing-metrics.adoc#querying-metrics-for-all-projects-as-an-administrator_managing-metrics[all projects] as a cluster administrator
+include::modules/gathering-data-specific-features.adoc[leveloffset=+1]
 
-include::modules/virt-collecting-data-about-vms.adoc[leveloffset=+1]
-
-[id="additional-resources_collecting-data-about-vms"]
-[role="_additional-resources"]
-=== Additional resources
-* Installing xref:../../virt/virtual_machines/virt-installing-qemu-guest-agent.adoc#virt-installing-virtio-drivers-existing-windows_virt-installing-qemu-guest-agent[VirtIO drivers] on Windows VMs
-* Downloading and installing link:https://access.redhat.com/solutions/6957701[VirtIO drivers] on Windows VMs without host access
-* Connecting to Windows VMs with RDP using the xref:../../virt/virtual_machines/virt-accessing-vm-consoles.adoc#virt-vm-rdp-console-web_virt-accessing-vm-consoles[web console] or the xref:../../virt/virtual_machines/virt-accessing-vm-consoles.adoc#virt-accessing-rdp-console_virt-accessing-vm-consoles[command line]
-* Collecting `must-gather` data about xref:../../virt/logging_events_monitoring/virt-collecting-virt-data.adoc#virt-must-gather-options_virt-collecting-virt-data[virtual machines]
-// * Collecting virtual machine memory dumps. [link TBD. CNV-20256]
-
-include::modules/virt-using-virt-must-gather.adoc[leveloffset=+1]
-
-include::modules/virt-must-gather-options.adoc[leveloffset=+2]
-
-[id="additional-resources_must-gather-virt"]
-[role="_additional-resources"]
-=== Additional resources
-* xref:../../support/gathering-cluster-data.adoc#about-must-gather_gathering-cluster-data[About the `must-gather` tool]
+include::modules/virt-must-gather-usage-targeted-vm-data.adoc[leveloffset=+1]