diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index d397c0c880..cec83ee1e1 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -26,8 +26,9 @@ **** xref:creating-a-telemetry-plugin.adoc[] *** xref:configuring-server-logging.adoc[] *** xref:collecting-logs-using-chectl.adoc[] -**** xref:monitoring-the-dev-workspace-operator.adoc[] -**** xref:monitoring-che.adoc[] +*** xref:troubleshoot:collecting-diagnostics-with-must-gather.adoc[] +*** xref:monitoring-the-dev-workspace-operator.adoc[] +*** xref:monitoring-che.adoc[] ** xref:configuring-networking.adoc[] *** xref:configuring-network-policies.adoc[] *** xref:configuring-che-hostname.adoc[] diff --git a/modules/administration-guide/pages/collecting-logs-using-chectl.adoc b/modules/administration-guide/pages/collecting-logs-using-chectl.adoc index 519fdbab01..8cb596a8de 100644 --- a/modules/administration-guide/pages/collecting-logs-using-chectl.adoc +++ b/modules/administration-guide/pages/collecting-logs-using-chectl.adoc @@ -42,3 +42,4 @@ Logs are automatically collected during the {prod-short} installation when insta .Additional resources * {link-prod-cli-documentation} +* xref:troubleshoot:collecting-diagnostics-with-must-gather.adoc[] diff --git a/modules/administration-guide/pages/configuring-observability.adoc b/modules/administration-guide/pages/configuring-observability.adoc index 88696e985c..0983dcf125 100644 --- a/modules/administration-guide/pages/configuring-observability.adoc +++ b/modules/administration-guide/pages/configuring-observability.adoc @@ -11,5 +11,6 @@ To configure {prod-short} observability features, see: * xref:configuring-server-logging.adoc[] * xref:collecting-logs-using-chectl.adoc[] +* xref:troubleshoot:collecting-diagnostics-with-must-gather.adoc[] * xref:monitoring-the-dev-workspace-operator.adoc[] * xref:monitoring-che.adoc[] diff --git a/modules/troubleshoot/nav.adoc b/modules/troubleshoot/nav.adoc index 7bbc552b3e..da88ae5e5e 100644 --- a/modules/troubleshoot/nav.adoc +++ b/modules/troubleshoot/nav.adoc @@ -11,6 +11,7 @@ ** xref:troubleshooting-devfile-issues.adoc[] * Troubleshoot the platform ** xref:viewing-workspace-logs-in-the-openshift-console.adoc[] +** xref:collecting-diagnostics-with-must-gather.adoc[] ** xref:troubleshooting-workspace-startup-failures.adoc[] ** xref:troubleshooting-network-problems.adoc[] ** xref:troubleshooting-oauth-configuration.adoc[] diff --git a/modules/troubleshoot/pages/collecting-diagnostics-with-must-gather.adoc b/modules/troubleshoot/pages/collecting-diagnostics-with-must-gather.adoc new file mode 100644 index 0000000000..11e5f206df --- /dev/null +++ b/modules/troubleshoot/pages/collecting-diagnostics-with-must-gather.adoc @@ -0,0 +1,47 @@ +:_content-type: PROCEDURE +:description: On {ocp}, collect {prod} and DevWorkspace diagnostic data with must-gather for support and troubleshooting. +:keywords: troubleshoot, must-gather, diagnostics, logs, support, openshift +:navtitle: Collect diagnostics with must-gather +:page-aliases: + +[id="collecting-diagnostics-with-must-gather"] += Collect diagnostics with must-gather + +[role="_abstract"] +On {ocp} clusters, you can collect a diagnostic snapshot of the {prod-short} Operator, {devworkspace}-based Cloud Development Environments, and related cluster state by using the {prod-short} community-supported must-gather image with `oc adm must-gather`. Share this dump with others so they can help troubleshoot the issue. + +.Prerequisites + +* You are running {prod-short} on an {ocp} cluster. +* The `oc` OpenShift CLI is installed and configured for the target cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. +* You have `cluster-admin` permissions on the cluster. +* {prod-short} is installed on the cluster. + +.Procedure + +. Collect {prod-short} and {devworkspace} diagnostics: ++ +[source,bash] +---- +$ oc adm must-gather --image=quay.io/che-incubator/must-gather:latest +---- ++ +The command creates a local directory named `must-gather.local.` that contains the diagnostic dump. ++ +[IMPORTANT] +==== +This must-gather image focuses on {prod-short}, {devworkspace}, and related components. +To collect full cluster data, run `oc adm must-gather` without specifying a custom image. +==== + +. Optional: Write the output to a specific directory: ++ +[source,bash,subs="+quotes"] +---- +$ oc adm must-gather --image=quay.io/che-incubator/must-gather:latest \ + --dest-dir=____ +---- + +.Verification + +* A local `must-gather.local.` directory (or the directory you passed to `--dest-dir`) exists and contains the diagnostic dump. diff --git a/modules/troubleshoot/pages/troubleshooting-che.adoc b/modules/troubleshoot/pages/troubleshooting-che.adoc index 75a86a3ef6..16de823694 100644 --- a/modules/troubleshoot/pages/troubleshooting-che.adoc +++ b/modules/troubleshoot/pages/troubleshooting-che.adoc @@ -19,6 +19,9 @@ The first step for any problem is to check the Cloud Development Environment log | Need to check logs | View logs from the CLI, the {orch-name} console, or the editor to identify errors and warnings. +| Need a full diagnostic dump for support on {ocp} +| On {ocp} clusters, collect {prod-short} Operator, {devworkspace}, and related cluster state with must-gather. See xref:collecting-diagnostics-with-must-gather.adoc[]. + | Cloud Development Environment fails to start | Diagnose pod scheduling, image pull, DevWorkspace, and resource quota errors from the dashboard or operator logs. diff --git a/modules/troubleshoot/pages/troubleshooting-workspace-startup-failures.adoc b/modules/troubleshoot/pages/troubleshooting-workspace-startup-failures.adoc index beb4fe10cf..622896235e 100644 --- a/modules/troubleshoot/pages/troubleshooting-workspace-startup-failures.adoc +++ b/modules/troubleshoot/pages/troubleshooting-workspace-startup-failures.adoc @@ -74,5 +74,6 @@ Diagnose and resolve common workspace startup failures based on error symptoms a .Additional resources +* xref:collecting-diagnostics-with-must-gather.adoc[] * xref:optimize:configuring-machine-autoscaling.adoc[] * xref:install:calculating-che-resource-requirements.adoc[]