--- title: Gathering data about your cluster --- # Gathering data about your cluster {#gathering-cluster-data} You can gather debugging information about your OpenShift Container Platform cluster to provide to Red Hat Support when opening a support case. ## About the must-gather tool {#about-must-gather_gathering-cluster-data} 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: ```terminal $ oc adm must-gather \ --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v4.22.6 ``` - To collect the audit logs, use the `-- /usr/bin/gather_audit_logs` argument, as described in a following section. For example: ```terminal $ 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. > - On a Windows operating system, install the `cwRsync` client and add to the `PATH` variable for use with the `oc rsync` command. 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` in the current working directory. For example: ```terminal 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: ```terminal $ oc adm must-gather --run-namespace \ --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v4.22.6 ``` ### Gathering data about your cluster for Red Hat Support {#support_gathering_data_gathering-cluster-data} You can gather debugging information about your cluster by using the `oc adm must-gather` CLI command. If you are gathering information to debug a self-managed hosted cluster, see "Gathering information to troubleshoot hosted control planes". **Prerequisites** - You have access to the cluster as a user with the `cluster-admin` role. - The OpenShift Container Platform CLI (`oc`) is installed. **Procedure** 1. Navigate to the directory where you want to store the `must-gather` data. > [!NOTE] > If your cluster is in a disconnected environment, you must take additional steps. If your mirror registry has a trusted CA, you must first add the trusted CA to the cluster. For all clusters in disconnected environments, you must import the default `must-gather` image as an image stream. > > ```terminal > $ oc import-image is/must-gather -n openshift > ``` 2. Run the `oc adm must-gather` command: ```terminal $ oc adm must-gather ``` > [!IMPORTANT] > If you are in a disconnected environment, use the `--image` flag as part of must-gather and point to the payload image. > [!NOTE] > Because this command picks a random control plane node by default, the pod might be scheduled to a control plane node that is in the `NotReady` and `SchedulingDisabled` state. 1. If this command fails, for example, if you cannot schedule a pod on your cluster, then use the `oc adm inspect` command to gather information for particular resources. > [!NOTE] > Contact Red Hat Support for the recommended resources to gather. 3. Create a compressed file from the `must-gather` directory that was just created in your working directory. Make sure you provide the date and cluster ID for the unique must-gather data. For more information about how to find the cluster ID, see [How to find the cluster-id or name on OpenShift cluster](https://access.redhat.com/solutions/5280291). For example, on a computer that uses a Linux operating system, run the following command: ```terminal $ tar cvaf must-gather-`date +"%m-%d-%Y-%H-%M-%S"`-.tar.gz ``` where: `` : Replace with the actual directory name. 4. Attach the compressed file to your support case on the [the **Customer Support** page](https://access.redhat.com/support/cases/#/case/list) of the Red Hat Customer Portal. ## Reducing the size of must-gather output {#support-must-gather-targeted-collection_gathering-cluster-data} The `oc adm must-gather` command collects comprehensive cluster information. However, a full data collection can result in a large file that is difficult to upload and analyze and could result in timeouts. To manage the output size and target your data collection for more effective troubleshooting, you can pass specific flags to the underlying `gather` script or scope the collection to particular resources. ### Gathering data for specific resources {#support-must-gather-targeted-collection-gathering-data_gathering-cluster-data} Instead of collecting data for the entire cluster, you can direct the `must-gather` tool to inspect a specific resource. This method is highly effective for isolating issues within a single project, Operator, or application. The `must-gather` tool uses `oc adm inspect` internally. You can specify what to inspect by passing the `inspect` command and its arguments after the `--` separator. **Procedure** - To gather data for a specific namespace, such as `my-project`, run the following command: ```terminal $ oc adm must-gather --dest-dir=my-project-must-gather -- oc adm inspect ns/my-project ``` - This command collects all standard resources within the `my-project` namespace, including logs from pods in that namespace, but excludes cluster-scoped resources. - To gather data related to a specific Cluster Operator, such as `openshift-apiserver`, run the following command: ```terminal $ oc adm must-gather --dest-dir=apiserver-must-gather -- oc adm inspect clusteroperator/openshift-apiserver ``` - To exclude rotated logs, such as `*.gz` or `*.1` files, from data collection, set the `REDUCE_LOGS` environment variable by running the following command: ```terminal $ oc adm must-gather -- REDUCE_LOGS=skip_rotated_logs /usr/bin/gather ``` - To exclude logs entirely and significantly reduce the size of the `must-gather` archive, add a double dash (`--`) after `oc adm must-gather` command and add the `--no-logs` argument: ```terminal $ oc adm must-gather -- /usr/bin/gather --no-logs ``` ### Must-gather flags {#must-gather-flags_gathering-cluster-data} The flags listed in the following table are available to use with the `oc adm must-gather` command. **OpenShift Container Platform flags for `oc adm must-gather`** | Flag | Example command | Description | | --- | --- | --- | | `--all-images` | `oc adm must-gather --all-images=false` | Collect `must-gather` data using the default image for all Operators on the cluster that are annotated with `operators.openshift.io/must-gather-image`. | | `--dest-dir` | `oc adm must-gather --dest-dir=''` | Set a specific directory on the local machine where the gathered data is written. | | `--host-network` | `oc adm must-gather --host-network=false` | Run `must-gather` pods as `hostNetwork: true`. Relevant if a specific command and image needs to capture host-level data. | | `--image` | `oc adm must-gather --image=[]` | Specify a `must-gather` plugin image to run. If not specified, OpenShift Container Platform's default `must-gather` image is used. | | `--image-stream` | `oc adm must-gather --image-stream=[]` | Specify an`` using a namespace or name:tag value containing a `must-gather` plugin image to run. | | `--node-name` | `oc adm must-gather --node-name=''` | Set a specific node to use. If not specified, by default a random master is used. | | `--node-selector` | `oc adm must-gather --node-selector=''` | Set a specific node selector to use. Only relevant when specifying a command and image which needs to capture data on a set of cluster nodes simultaneously. | | `--run-namespace` | `oc adm must-gather --run-namespace=''` | An existing privileged namespace where `must-gather` pods should run. If not specified, a temporary namespace is generated. | | `--since` | `oc adm must-gather --since=