must-gather for 4.13

backup_and_restore/application_backup_and_restore/troubleshooting.adoc

@@ -137,8 +137,6 @@ include::modules/migration-using-must-gather.adoc[leveloffset=+1]
 .Additional resources
 * xref:../../support/gathering-cluster-data.adoc#gathering-cluster-data[Gathering cluster data]
 
-include::modules/support-insecure-tls-connections.adoc[leveloffset=+2]
-include::modules/migration-combining-must-gather.adoc[leveloffset=+2]
 include::modules/oadp-monitoring.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources

modules/migration-using-must-gather.adoc

@@ -8,20 +8,23 @@
 [id="migration-using-must-gather_{context}"]
 = Using the must-gather tool
 
-You can collect logs, metrics, and information about {local-product} custom resources by using the `must-gather` tool.
+You can collect logs, and information about {local-product} custom resources by using the `must-gather` tool.
 
 The `must-gather` data must be attached to all customer cases.
 
+The `must-gather` tool is a container and does not run all the time. The tool runs for a few minutes only when a user invokes the tool by running the `must-gather` command.
+
 ifdef::troubleshooting-3-4,troubleshooting-mtc[]
 You can collect data for a one-hour or a 24-hour period and view the data with the Prometheus console.
 endif::[]
 ifdef::oadp-troubleshooting[]
-You can run the `must-gather` tool with the following data collection options:
+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 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.
 
-* 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.
+The `must-gather` tool generates a Markdown output file with the collected information. The Markdown file is located in a cluster directory.
 endif::[]
 
 .Prerequisites
@@ -75,38 +78,52 @@ $ oc adm must-gather --image=registry.redhat.io/rhmtc/openshift-migration-must-g
 This operation can take a long time. This command saves the data as the `must-gather/metrics/prom_data.tar.gz` file.
 endif::[]
 ifdef::oadp-troubleshooting[]
-* Full `must-gather` data collection, including Prometheus metrics:
+* 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-3} -- /usr/bin/gather -h
+----
+
+* 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-3}
 ----
 +
-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 Hat Customer Portal].
-
-* Essential `must-gather` data collection, without Prometheus metrics, for a specific time duration:
+[source,terminal,subs="attributes+"]
+----
+$ oc adm must-gather --image={must-gather-v1-3} -- /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-3} \
-  -- /usr/bin/gather_<time>_essential <1>
+$ oc adm must-gather --image={must-gather-v1-3} -- /usr/bin/gather --request-timeout 1m # <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`.
-
-* `must-gather` data collection with timeout:
+<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-3} \
-  -- /usr/bin/gather_with_timeout <timeout> <1>
+$ oc adm must-gather --image={must-gather-v1-3} -- /usr/bin/gather --skip-tls
 ----
-<1> Specify a timeout value in seconds.
-
-* Prometheus metrics data dump:
+* 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-3} -- /usr/bin/gather_metrics_dump
+$ oc adm must-gather --image={must-gather-v1-3} -- /usr/bin/gather --request-timeout 15s --skip-tls #<1>
 ----
-This operation can take a long time. The data is saved as `must-gather/metrics/prom_data.tar.gz`.
+<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]
 endif::[]