OADP must-gather 4.18 4.17 4.16

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

@@ -1,76 +1,17 @@
-:_mod-docs-content-type: ASSEMBLY
 [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`.
+include::modules/using-must-gather.adoc[leveloffset=+1]
 
+include::modules/running-must-gather-help.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]
+* xref:../../support/gathering-cluster-data.adoc#gathering-cluster-data[Gathering cluster data]

modules/running-must-gather-help.adoc

@@ -0,0 +1,24 @@
+// 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-help_{context}"]
+= Running must-gather with the help flag
+
+Use the `-h` help flag to review the usage of the `must-gather` tool.
+
+.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
+
+* To review the supported flags for the `oc adm must-gather` command, run the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image={must-gather-v1-4} -- /usr/bin/gather -h
+----

modules/using-must-gather.adoc

@@ -0,0 +1,68 @@
+// 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, you can add a flag corresponding to that option in the `must-gather` command.
+
+Default configuration:: This configuration collects Prometheus metrics, pod logs, and Velero 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.
+
+.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:
+
+* To use the default configuration of the `must-gather` tool, run either one of the following commands:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image={must-gather-v1-4}
+----
++
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image={must-gather-v1-4} -- /usr/bin/gather
+----
++
+* 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.
+
+.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]