Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 7. Troubleshoot

You can open a Red Hat support case and provide debugging information by using must-gather. The must-gather tool collects diagnostic information about your OpenShift Container Platform cluster, including virtual machines and other data.

7.1. Using must-gather
Copy link

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.

    For example: 

    $ oc adm must-gather --image=registry.redhat.io/openshift-sandboxed-containers/osc-must-gather-rhel9:1.12.0

  • To collect the audit logs, use the -- /usr/bin/gather_audit_logs argument, as described in a following section.

    For example: 

    $ oc adm must-gather -- /usr/bin/gather_audit_logs
    Note

    Audit 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.

For example: 

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.

For example: 

$ oc adm must-gather --run-namespace <namespace> --image=registry.redhat.io/openshift-sandboxed-containers/osc-must-gather-rhel9:1.12.0

7.2. KataConfig status messages
Copy link

The following table displays the status messages for the KataConfig custom resource (CR) for a cluster with two worker nodes.

Expand
Table 7.1. KataConfig status messages
StatusDescription

Initial installation

When a KataConfig CR is created and starts installing kata-cc on both workers, the following status is displayed for a few seconds. 

 conditions:
    message: Performing initial installation of kata-cc on cluster
    reason: Installing
    status: 'True'
    type: InProgress
 kataNodes:
   nodeCount: 0
   readyNodeCount: 0

Installing

Within a few seconds the status changes. 

 kataNodes:
   nodeCount: 2
   readyNodeCount: 0
   waitingToInstall:
   - worker-0
   - worker-1

Installing (Worker-1 installation starting)

For a short period of time, the status changes, signifying that one node has initiated the installation of kata-cc, while the other is in a waiting state. This is because only one node can be unavailable at any given time. The nodeCount remains at 2 because both nodes will eventually receive kata-cc, but the readyNodeCount is currently 0 as neither of them has reached that state yet. 

 kataNodes:
   installing:
   - worker-1
   nodeCount: 2
   readyNodeCount: 0
   waitingToInstall:
   - worker-0

Installing (Worker-1 installed, worker-0 installation started)

After some time, worker-1 will complete its installation, causing a change in the status. The readyNodeCount is updated to 1, indicating that worker-1 is now prepared to execute kata-cc workloads. You cannot schedule or run kata-cc workloads until the runtime class is created at the end of the installation process. 

 kataNodes:
   installed:
   - worker-1
   installing:
   - worker-0
   nodeCount: 2
   readyNodeCount: 1

Installed

When installed, both workers are listed as installed, and the InProgress condition transitions to False without specifying a reason, indicating the successful installation of kata-cc on the cluster. 

 conditions:
    message: ""
    reason: ""
    status: 'False'
    type: InProgress
 kataNodes:
   installed:
   - worker-0
   - worker-1
   nodeCount: 2
   readyNodeCount: 2
Expand
StatusDescription

Initial uninstall

If kata-cc is installed on both workers, and you delete the KataConfig to remove kata-cc from the cluster, both workers briefly enter a waiting state for a few seconds. 

 conditions:
    message: Removing kata-cc from cluster
    reason: Uninstalling
    status: 'True'
    type: InProgress
 kataNodes:
   nodeCount: 0
   readyNodeCount: 0
   waitingToUninstall:
   - worker-0
   - worker-1

Uninstalling

After a few seconds, one of the workers starts uninstalling. 

 kataNodes:
   nodeCount: 0
   readyNodeCount: 0
   uninstalling:
   - worker-1
   waitingToUninstall:
   - worker-0

Uninstalling

Worker-1 finishes and worker-0 starts uninstalling. 

 kataNodes:
   nodeCount: 0
   readyNodeCount: 0
   uninstalling:
   - worker-0
Note

The reason field can also report the following causes:

  • Failed: This is reported if the node cannot finish its transition. The status reports True and the message is Node <node_name> Degraded: <error_message_from_the_node>.
  • BlockedByExistingKataPods: This is reported if there are pods running on a cluster that use the kata-cc runtime while kata-cc is being uninstalled. The status field is False and the message is Existing pods using "kata-cc" RuntimeClass found. Please delete the pods manually for KataConfig deletion to proceed. There could also be a technical error message reported like Failed to list kata pods: <error_message> if communication with the cluster control plane fails.
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