Using the must-gather tool

Using the must-gather tool

You can collect logs and information about OADP custom resources by using the must-gather tool. The must-gather data must be attached to all customer cases.

The must-gather tool is a container and does not run all the time. The tool runs for a few minutes only after you invoke the tool by running the must-gather command.

You can run the must-gather tool with the following options. To use an option, you can add a flag corresponding to that option in the must-gather command.

Default configuration: This configuration collects pod logs, OADP and Velero custom resource (CR) information for all namespaces where the OADP Operator is installed.
Timeout: Data collection can take a long time if there are many failed Backup CRs. You can improve performance by setting a timeout value.
Insecure TLS connections: If a custom CA certificate is used, use the must-gather tool with insecure TLS connections.

The must-gather tool generates a Markdown output file with the collected information. The Markdown file is located in a cluster directory.

Prerequisites

You have logged in to the OKD cluster as a user with the cluster-admin role.
You have installed the OpenShift CLI (oc).
You are using OADP 1.3 or 1.4.

Procedure

Navigate to the directory where you want to store the must-gather data.
Run the oc adm must-gather command for one of the following data collection options:
- To use the default configuration of the must-gather tool, run one of the following commands:
  - For OADP 1.3, run the following command:
    
    $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.3
  - For OADP 1.4, run the following command:
    
    $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4
- To use the timeout flag with the must-gather tool, run one of the following commands:
  - For OADP 1.3, run the following command:
    
    $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.3 -- /usr/bin/gather --request-timeout <timeout> (1)
    
    1 Specify a timeout value.
  - For OADP 1.4, run the following command:
    
    $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4 -- /usr/bin/gather_with_timeout <timeout> (1)
    
    1 Specify a timeout value in seconds.
- To use the insecure TLS connection flag with the must-gather tool, run one of the following commands:
  - For OADP 1.3, run the following command:
    
    $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.3 -- /usr/bin/gather --skip-tls
  - For OADP 1.4, run the following command:
    
    $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4 -- /usr/bin/gather_without_tls <value> (1)
    
    1 By default, the value is false. Set to true to allow insecure TLS connections.
- To use a combination of the insecure TLS connection, and the timeout flags with the must-gather tool, run one of the following commands:
  - For OADP 1.3, run the following command:
    
    $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.3 -- /usr/bin/gather --request-timeout 15s --skip-tls=true (1)
    
    1 By default, the --skip-tls flag value is false. Set the value to true to allow insecure TLS connections. Specify a timeout value.
  - For OADP 1.4, run the following command:
    
    $ oc adm must-gather --image=registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4 --skip_tls=true /usr/bin/gather_with_timeout <timeout_value_in_seconds> (1)
    
    1 By default, the --skip-tls flag value is false. Set the value to true to allow insecure TLS connections. Specify a timeout value.

Verification

Verify that the Markdown output file is generated at the following location: must-gather.local.89…054550/registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.5-sha256-0…84/clusters/a4…86/oadp-must-gather-summary.md
Review the must-gather data in the Markdown file by opening the file in a Markdown previewer. For an example output, refer to the following image. You can upload this output file to a support case on the Red Hat Customer Portal.

Figure 1. Example markdown output of must-gather tool

Additional resources

Gathering cluster data