Skip to content

OADP must-gather for 1.4.5 #95588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: enterprise-4.18
Choose a base branch
from
Open

OADP must-gather for 1.4.5 #95588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0a1dffb
OADP must-gather for 1.4.5
shdeshpa07 Jul 3, 2025
daacdb9
attribute error
shdeshpa07 Jul 3, 2025
86df29d
Apply suggestions from code review
shdeshpa07 Jul 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 5 additions & 60 deletions .../application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,75 +2,20 @@
[id="using-the-must-gather-tool"]
= Using the must-gather tool
include::_attributes/common-attributes.adoc[]
include::_attributes/attributes-openshift-dedicated.adoc[]
:context: using-the-must-gather-tool
:namespace: openshift-adp
:local-product: OADP
:must-gather-v1-3: registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.3
:must-gather-v1-4: registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4

toc::[]

You can collect logs, metrics, and information about {local-product} custom resources by using the `must-gather` tool. The `must-gather` data must be attached to all customer cases.
You can collect logs and information about {oadp-short} custom resources by using the `must-gather` tool. The `must-gather` data must be attached to all customer cases.

You can run the `must-gather` tool with the following data collection options:

* Full `must-gather` data collection collects Prometheus metrics, pod logs, and Velero CR information for all namespaces where the OADP Operator is installed.
* Essential `must-gather` data collection collects pod logs and Velero CR information for a specific duration of time, for example, one hour or 24 hours. Prometheus metrics and duplicate logs are not included.
* `must-gather` data collection with timeout. Data collection can take a long time if there are many failed `Backup` CRs. You can improve performance by setting a timeout value.
* Prometheus metrics data dump downloads an archive file containing the metrics data collected by Prometheus.


.Prerequisites

* You have logged in to the {product-title} cluster as a user with the `cluster-admin` role.
* You have installed the OpenShift CLI (`oc`).
* You must use {op-system-base-full} {op-system-version-9} with {oadp-short} 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:

* For full `must-gather` data collection, including Prometheus metrics, run the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4}
----
+
The data is saved as `must-gather/must-gather.tar.gz`. You can upload this file to a support case on the link:https://access.redhat.com/[Red{nbsp}Hat Customer Portal].
+
For essential `must-gather` data collection, without Prometheus metrics, for a specific time duration, run the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4} \
-- /usr/bin/gather_<time>_essential <1>
----
<1> Specify the time in hours. Allowed values are `1h`, `6h`, `24h`, `72h`, or `all`, for example, `gather_1h_essential` or `gather_all_essential`.

* For `must-gather` data collection with timeout, run the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4} \
-- /usr/bin/gather_with_timeout <timeout> <1>
----
<1> Specify a timeout value in seconds.

* For a Prometheus metrics data dump, run the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4} -- /usr/bin/gather_metrics_dump
----
This operation can take a long time. The data is saved as `must-gather/metrics/prom_data.tar.gz`.
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.

include::modules/using-must-gather.adoc[leveloffset=+1]

[role="_additional-resources"]
.Additional resources
* xref:../../../support/gathering-cluster-data.adoc#gathering-cluster-data[Gathering cluster data]

include::modules/support-insecure-tls-connections.adoc[leveloffset=+1]
include::modules/migration-combining-must-gather.adoc[leveloffset=+1]
//unset attributes
:!must-gather-v1-4:
Binary file added images/oadp-must-gather-markdown-output.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
72 changes: 72 additions & 0 deletions modules/using-must-gather.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
// Module included in the following assemblies:
//
// * backup_and_restore/application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc

:_mod-docs-content-type: PROCEDURE
[id="oadp-running-must-gather_{context}"]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From OpenShift docs guidelines:

The anchor ID with _{context} must be lowercase and match the module’s file name.

Similarly in modularization guidelines:

At the top of every module, provide an anchor in the format [id="filename_{context}"] where filename is the exact name of the file, without the file extension (.adoc) and a module prefix

So I would recommend either renaming the file or changing the ID, so that the ID and file name matches

= Using the must-gather tool

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

Default configuration:: This configuration collects pod logs, {oadp-short}, and `Velero` custom resource (CR) information for all namespaces where the {oadp-short} 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, run 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.

For more information about the supported flags, use the help flag with the `must-gather` tool as shown in the following example:

[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4} -- /usr/bin/gather -h
----
Comment on lines +17 to +22
Copy link
Contributor

@eromanova97 eromanova97 Jul 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not usually see commands in the introduction of a procedure.

Could it be possibly moved to the procedure? and if not, maybe putting this into a note would work better here?


.Prerequisites

* You have logged in to the {product-title} cluster as a user with the `cluster-admin` role.
* You have installed the {oc-first}.
* You must use {op-system-base-full} {op-system-version-9} with {oadp-short} 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 the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4}
----

** To use the timeout flag with the `must-gather` tool, run the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4} -- /usr/bin/gather --request-timeout 1m <1>
----
<1> In this example, the timeout is 1 minute.

** To use the insecure TLS connection flag with the `must-gather` tool, run the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4} -- /usr/bin/gather --skip-tls
----

** To use a combination of the insecure TLS connection, and the timeout flags with the `must-gather` tool, run the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc adm must-gather --image={must-gather-v1-4} -- /usr/bin/gather --request-timeout 15s --skip-tls <1>
----
<1> In this example, the timeout is 15 seconds. By default, the `--skip-tls` flag value is `false`. Set the value to `true` to allow insecure TLS connections.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By default, the --skip-tls flag value is false. Set the value to true to allow insecure TLS connections.

The --skip-tls option is already used in the previous example command, so it would be better to explain this behavior sooner. It could be moved to the decription of "Insecure TLS connections" in the introduction.


.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 link:https://access.redhat.com/[Red{nbsp}Hat Customer Portal].
+
.Example markdown output
image::oadp-must-gather-markdown-output.png[must-gather markdown output]