OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Collecting data for Red Hat Support

When you submit a support case to Red Hat Support, it is helpful to provide debugging information for OpenShift Container Platform and OpenShift Virtualization by using the following tools:

must-gather tool

The must-gather tool collects diagnostic information, including resource definitions and service logs.

Prometheus

Prometheus is a time-series database and a rule evaluation engine for metrics. Prometheus sends alerts to Alertmanager for processing.

Alertmanager

The Alertmanager service handles alerts received from Prometheus. The Alertmanager is also responsible for sending the alerts to external notification systems.

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

  1. Collect must-gather data for the cluster by using the default must-gather image.

  2. Collect must-gather data for Red Hat OpenShift Data Foundation, if necessary.

  3. Collect must-gather data for OpenShift Virtualization by using the OpenShift Virtualization must-gather image.

  4. Collect Prometheus metrics for the cluster.

Additional resources

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

  1. Collect detailed must-gather data about the malfunctioning VMs.

  2. Collect screenshots of VMs that have crashed before you restart them.

  3. Record factors that the malfunctioning VMs have in common. For example, the VMs have the same host or network.

Additional resources

Using the must-gather tool for OpenShift Virtualization

You can collect data about OpenShift Virtualization resources by running the must-gather command with the OpenShift Virtualization image.

The default data collection includes information about the following resources:

  • OpenShift Virtualization Operator namespaces, including child objects

  • OpenShift Virtualization custom resource definitions

  • Namespaces that contain virtual machines

  • Basic virtual machine definitions

Procedure

  • Run the following command to collect data about OpenShift Virtualization:

    $ oc adm must-gather --image-stream=openshift/must-gather \
  --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v4.12.15

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, image-stream, and image-stream-tags information

  • Limiting the maximum number of parallel processes used by the must-gather tool

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.

Using too many parallel processes can cause performance issues. Increasing the maximum number of parallel processes is not recommended.
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.

/usr/bin/gather --vms_details

Collect VM log files, VM definitions, control-plane logs, and namespaces that belong to OpenShift Virtualization 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.

/usr/bin/gather --images

Collect image, image-stream, and image-stream-tags custom resource information. This script is compatible only with the PROS variable.

Usage and examples

Environment variables are optional. You can run a script by itself or with one or more compatible environment variables.

Table 1. Compatible parameters
Script Compatible environment variable

/usr/bin/gather

  • PROS=<number_of_processes>

/usr/bin/gather --vms_details

  • For a namespace: NS=<namespace_name>

  • For a VM: VM=<vm_name> NS=<namespace_name>

  • PROS=<number_of_processes>

/usr/bin/gather --images

  • PROS=<number_of_processes>
Syntax
$ oc adm must-gather \
  --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v4.12.15 \
  -- <environment_variable_1> <environment_variable_2> <script_name>
Default data collection parallel processes

By default, five processes run in parallel.

$ oc adm must-gather \
  --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v4.12.15 \
  -- 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:

$ oc adm must-gather \
  --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v4.12.15 \
  -- 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:

$ oc adm must-gather \
  --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v4.12.15 \
  -- /usr/bin/gather --images

Additional resources