SupportConsoleDevelopersStart a trialContact

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 Pipelines components.

Note

For prompt support, provide diagnostic information for both OpenShift Container Platform and Red Hat OpenShift Pipelines.

3.1. About the must-gather tool
Copy link

The oc adm must-gather tool collects diagnostic information about your cluster, such as resource definitions, configurations, and logs for project-level and cluster-level resources.

When you run the command, the tool performs the following actions:

  • Creates a new namespace on the cluster specifically for the collection process.
  • Spawns one or more must-gather pods within that namespace.
  • Executes scripts inside the pods to gather logs, custom resource definitions (CRDs), and system states from the relevant nodes and control plane components.
  • Streams the collected data back to your local machine and saves it into a newly created directory starting with ./must-gather.local.

By default, the tool collects data across core cluster components. When troubleshooting issues specific to Red Hat OpenShift Pipelines, you specify the OpenShift Pipelines must-gather image to capture components like the operator subscription, Tekton configurations, task runs, pipeline runs, and pod logs in the operator namespaces.

3.2. Collecting OpenShift Pipelines debugging data
Copy link

You can use the oc adm must-gather CLI command to collect detailed diagnostic data and logs for OpenShift Pipelines components on your cluster.

Prerequisites

  • You have access to the cluster as a user with the cluster-admin cluster role.
  • You have installed the OpenShift CLI (oc).

Procedure

  1. Navigate to the directory where you want to store the debugging information.

  2. Run the oc adm must-gather command with the OpenShift Pipelines must-gather image: 

    $ oc adm must-gather --image=quay.io/openshift-pipeline/must-gather

    The must-gather tool creates a new directory starting with ./must-gather.local in your current directory, for example, ./must-gather.local.4157245944708210399.

  3. Create a compressed file from the directory created by the must-gather tool. For example, on a computer running a Linux operating system, run the following command: 

    $ tar -cvaf must-gather.tar.gz must-gather.local.<random-hash>

    Replace must-gather.local.<random-hash> with the actual name of the generated directory.

Verification

  1. Verify that the compressed file exists in your current directory: 

    $ ls -lh must-gather.tar.gz

    Example output 

    -rw-r--r--. 1 user user 2.5M Jun 26 14:30 must-gather.tar.gz
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top