OADP must-gather 2.0

Signed-off-by: Shruti Deshpande <[email protected]>

Author: shdeshpa07

backup_and_restore/application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc

@@ -2,75 +2,17 @@
 [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
+:must-gather-v1-5: registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.5
 
 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]

images/oadp-must-gather-markdown-output.png

@@ -0,0 +1,70 @@
+// Module included in the following assemblies:
+//
+// * backup_and_restore/application_backup_and_restore/using-the-must-gather-tool.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="oadp-running-must-gather_{context}"]
+= 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, use 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]
+----
+$ oc adm must-gather --image={must-gather-v1-5} -- /usr/bin/gather -h
+----
+
+
+.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`).
+
+.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-5}
+----
++
+* 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-5} -- /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-5} -- /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-5} -- /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.
+
+.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 of must-gather tool
+image::oadp-must-gather-markdown-output.png[must-gather markdown output]