Chapter 3. Gathering diagnostic information for support
When you open a support case, you must provide debugging information about your cluster to the Red Hat Support team. You can use the must-gather
tool to collect diagnostic information for project-level resources, cluster-level resources, and Red Hat OpenShift GitOps components.
For prompt support, provide diagnostic information for both OpenShift Container Platform and Red Hat OpenShift GitOps.
3.1. About the must-gather tool
The oc adm must-gather
CLI command collects the information from your cluster that is most likely needed for debugging issues, including:
- Resource definitions
- Service logs
By default, the oc adm must-gather
command uses the default plugin image and writes into ./must-gather.local
.
Alternatively, you can collect specific information by running the command with the appropriate arguments as described in the following sections:
To collect data related to one or more specific features, use the
--image
argument with an image, as listed in a following section.Example command
$ oc adm must-gather --image=registry.redhat.io/openshift-gitops-1/must-gather-rhel8:v1.10.0
To collect the audit logs, use the
-- /usr/bin/gather_audit_logs
argument, as described in a following section.Example command
$ oc adm must-gather -- /usr/bin/gather_audit_logs
NoteAudit logs are not collected as part of the default set of information to reduce the size of the files.
When you run oc adm must-gather
, a new pod with a random name is created in a new project on the cluster. The data is collected on that pod and saved in a new directory that starts with must-gather.local
. This directory is created in the current working directory.
Example pod
NAMESPACE NAME READY STATUS RESTARTS AGE ... openshift-must-gather-5drcj must-gather-bklx4 2/2 Running 0 72s openshift-must-gather-5drcj must-gather-s8sdh 2/2 Running 0 72s ...
Optionally, you can run the oc adm must-gather
command in a specific namespace by using the --run-namespace
option.
Example command
$ oc adm must-gather --image=registry.redhat.io/openshift-gitops-1/must-gather-rhel8:v1.10.0
3.2. Collecting debugging data for Red Hat OpenShift GitOps
Use the oc adm must-gather
CLI command to collect the following details about the cluster that is associated with Red Hat OpenShift GitOps:
- The subscription and namespace of the Red Hat OpenShift GitOps Operator.
-
The namespaces where ArgoCD objects are available and the objects in those namespaces, such as
ArgoCD
,Applications
,ApplicationSets
,AppProjects
, andconfigmaps
. - A list of the namespaces that are managed by the Red Hat OpenShift GitOps Operator, and resources from those namespaces.
- All GitOps-related custom resource objects and definitions.
- Operator and Argo CD logs.
- Warning and error-level events.
Prerequisites
- You have logged in to the OpenShift Container Platform cluster as an administrator.
-
You have installed the OpenShift Container Platform CLI (
oc
). - You have installed the Red Hat OpenShift GitOps Operator.
Procedure
- Navigate to the directory where you want to store the debugging information.
Run the
oc adm must-gather
command with the Red Hat OpenShift GitOpsmust-gather
image:$ oc adm must-gather --image=registry.redhat.io/openshift-gitops-1/must-gather-rhel8:<image_version_tag> 1
- 1
- The must-gather image for GitOps.
Example command
$ oc adm must-gather --image=registry.redhat.io/openshift-gitops-1/must-gather-rhel8:v1.10.0
The
must-gather
tool creates a new directory that starts with./must-gather.local
in the current directory. For example,./must-gather.local.4157245944708210399
.Create a compressed file from the directory that was just created. For example, on a computer that uses a Linux operating system, run the following command:
$ tar -cvaf must-gather.tar.gz must-gather.local.4157245944708210399 1
- 1
- Replace
must-gather-local.4157245944708210399
with the actual directory name.
- Attach the compressed file to your support case on the Red Hat Customer Portal.