CNV-15574: Troubleshooting guide assembly

apinnick · apinnick · commit 9b98b8afdcea · 2022-08-25T14:04:34.000+03:00
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -3454,7 +3454,7 @@ Topics:
     File: virt-exposing-custom-metrics-for-vms
   - Name: OpenShift Virtualization critical alerts
     File: virt-virtualization-alerts
-  - Name: Collecting OpenShift Virtualization data for Red Hat Support
+  - Name: Collecting data for Red Hat Support
     File: virt-collecting-virt-data
     Distros: openshift-enterprise
 - Name: Backup and restore
diff --git a/modules/virt-about-collecting-virt-data.adoc b/modules/virt-about-collecting-virt-data.adoc
diff --git a/modules/virt-collecting-data-about-vms.adoc b/modules/virt-collecting-data-about-vms.adoc
@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// * virt/logging_events_monitoring/virt-collecting-virt-data.adoc
+
+:_content-type: PROCEDURE
+[id="virt-collecting-data-about-vms_{context}"]
+= Collecting data about virtual machines
+
+Collecting data about malfunctioning virtual machines (VMs) minimizes the time required to analyze and determine the root cause.
+
+.Prerequisites
+
+* Windows VMs:
+** Record the Windows patch update details for Red Hat Support.
+** Install the latest version of the VirtIO drivers. The VirtIO drivers include the QEMU guest agent.
+** If Remote Desktop Protocol (RDP) is enabled, try to connect to the VMs with RDP to determine whether there is a problem with the connection software.
+
+.Procedure
+
+. Collect detailed `must-gather` data about the malfunctioning VMs.
+. Collect screenshots of VMs that have crashed before you restart them.
+. Record factors that the malfunctioning VMs have in common. For example, the VMs have the same host or network.
+// . Collect memory dumps from VMs _before_ remediation attempts.
+// Uncomment this line for CNV-20256.
diff --git a/modules/virt-collecting-data-about-your-environment.adoc b/modules/virt-collecting-data-about-your-environment.adoc
@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// * virt/logging_events_monitoring/virt-collecting-virt-data.adoc
+
+:_content-type: PROCEDURE
+[id="virt-collecting-data-about-your-environment_{context}"]
+= Collecting data about your environment
+
+Collecting data about your environment minimizes the time required to analyze and determine the root cause.
+
+.Prerequisites
+
+* Set the retention time for Prometheus metrics data to a minimum of seven days.
+* Configure the Alertmanager to capture relevant alerts and to send them to a dedicated mailbox so that they can be viewed and persisted outside the cluster.
+* Record the exact number of affected nodes and virtual machines.
+
+.Procedure
+
+. Collect `must-gather` data for the cluster by using the default `must-gather` image.
+. Collect `must-gather` data for {rh-storage-first}, if necessary.
+. Collect `must-gather` data for {VirtProductName} by using the {VirtProductName} `must-gather` image.
+. Collect Prometheus metrics for the cluster.
diff --git a/modules/virt-must-gather-options.adoc b/modules/virt-must-gather-options.adoc
@@ -0,0 +1,106 @@
+// Module included in the following assemblies:
+//
+// * virt/logging_events_monitoring/virt-collecting-virt-data.adoc
+
+[id="virt-must-gather-options_{context}"]
+= must-gather tool 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 and image stream information
+* Limiting the maximum number of parallel processes used by the `must-gather` tool
+
+[id="parameters"]
+== Parameters
+
+.Environment variables
+
+You can specify environment variables for a compatible script.
+
+`NS=<namespace_name>`:: 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.
+
+`VM=<vm_name>`:: Collect 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. The default value is `5`.
++
+[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 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.
+
+`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.
+
+[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.
+
+[cols="1a,1a", options="header"]
+.Compatible parameters
+|===
+|Script |Compatible environment variable
+|`gather_vms_details`
+|* For a namespace: `NS=<namespace_name>`
+
+* For a VM: `VM=<vm_name> NS=<namespace_name>`
+
+* `PROS=<number_of_processes>`
+
+|`gather`   |* `PROS=<number_of_processes>`
+|`gather_images`   |* `PROS=<number_of_processes>`
+|===
+
+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 \
+  --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion} \
+  -- <environment_variable_1> <environment_variable_2> <script_name>
+----
+
+.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-rhel8:v{HCOVersion} \
+  -- NS=mynamespace VM=my-vm 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:
+
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather \
+  --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8: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-rhel8:v{HCOVersion} \
+  -- gather_images
+----
diff --git a/modules/virt-must-gather-usage-targeted-vm-data.adoc b/modules/virt-must-gather-usage-targeted-vm-data.adoc
diff --git a/modules/virt-using-virt-must-gather.adoc b/modules/virt-using-virt-must-gather.adoc
@@ -0,0 +1,28 @@
+// 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: PROCEDURE
+[id="virt-using-virt-must-gather_{context}"]
+= Using the must-gather tool for {VirtProductName}
+
+You can collect data about {VirtProductName} resources by running the `must-gather` command with the {VirtProductName} image.
+
+The default data collection includes information about the following resources:
+
+* {VirtProductName} Operator namespaces, including child objects
+* {VirtProductName} custom resource definitions
+* Namespaces that contain virtual machines
+* Basic virtual machine definitions
+
+.Procedure
+
+* Run the following command to collect data about {VirtProductName}:
++
+[source,terminal]
+----
+$ oc adm must-gather --image-stream=openshift/must-gather \
+  --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion}
+----
diff --git a/virt/logging_events_monitoring/virt-collecting-virt-data.adoc b/virt/logging_events_monitoring/virt-collecting-virt-data.adoc
@@ -1,25 +1,50 @@
 :_content-type: ASSEMBLY
 include::_attributes/common-attributes.adoc[]
 [id="virt-collecting-virt-data"]
-= Collecting {VirtProductName} data for Red Hat Support
+= Collecting data for Red Hat Support
 :context: virt-collecting-virt-data
 
 toc::[]
 
-When opening a support case, it is helpful to provide debugging
-information about your cluster to Red Hat Support.
+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:
 
-The `must-gather` tool enables you to collect diagnostic information about your
-{product-title} cluster, including virtual machines and other data related to
-{VirtProductName}.
+must-gather tool::
+The `must-gather` tool collects diagnostic information, including resource definitions and service logs.
 
-For prompt support, supply diagnostic information for both {product-title}
-and {VirtProductName}.
+Prometheus::
+Prometheus is a time-series database and a rule evaluation engine for metrics. Prometheus sends alerts to Alertmanager for processing.
 
-include::modules/about-must-gather.adoc[leveloffset=+1]
+Alertmanager::
+The Alertmanager service handles alerts received from Prometheus. The Alertmanager is also responsible for sending the alerts to external notification systems.
 
-include::modules/virt-about-collecting-virt-data.adoc[leveloffset=+1]
+include::modules/virt-collecting-data-about-your-environment.adoc[leveloffset=+1]
 
-include::modules/gathering-data-specific-features.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/virt-must-gather-usage-targeted-vm-data.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]
