From ba9c2577d19119549a3dcf8a5b307a6d1e3c3304 Mon Sep 17 00:00:00 2001 From: Rohan Kumar Date: Wed, 29 Jul 2026 22:20:48 +0530 Subject: [PATCH 1/2] docs: add must-gather diagnostic collection for OpenShift Document how to collect a Che and DevWorkspace diagnostic snapshot with oc adm must-gather so it can be shared for troubleshooting. Co-authored-by: Cursor Signed-off-by: Rohan Kumar --- modules/observe/nav.adoc | 1 + .../pages/collecting-logs-using-chectl.adoc | 1 + modules/troubleshoot/nav.adoc | 1 + ...llecting-diagnostics-with-must-gather.adoc | 47 +++++++++++++++++++ .../pages/troubleshooting-che.adoc | 3 ++ ...leshooting-workspace-startup-failures.adoc | 1 + 6 files changed, 54 insertions(+) create mode 100644 modules/troubleshoot/pages/collecting-diagnostics-with-must-gather.adoc diff --git a/modules/observe/nav.adoc b/modules/observe/nav.adoc index c6e653f715..709d64c8ad 100644 --- a/modules/observe/nav.adoc +++ b/modules/observe/nav.adoc @@ -1,6 +1,7 @@ .Platform monitoring and telemetry * xref:configuring-observability.adoc[] * xref:monitoring-che.adoc[] +* xref:troubleshoot:collecting-diagnostics-with-must-gather.adoc[] * xref:monitoring-the-dev-workspace-operator.adoc[] * xref:the-woopra-telemetry-plugin.adoc[] diff --git a/modules/observe/pages/collecting-logs-using-chectl.adoc b/modules/observe/pages/collecting-logs-using-chectl.adoc index bceffd12d3..1b7d944e81 100644 --- a/modules/observe/pages/collecting-logs-using-chectl.adoc +++ b/modules/observe/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/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..7172c39a38 --- /dev/null +++ b/modules/troubleshoot/pages/collecting-diagnostics-with-must-gather.adoc @@ -0,0 +1,47 @@ +:_content-type: PROCEDURE +:description: On {ocp}, collect Eclipse Che 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} 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[] From 692e3da6ce539f471162d15957077a9a87149304 Mon Sep 17 00:00:00 2001 From: Rohan Kumar Date: Fri, 4 Sep 2026 20:40:04 +0530 Subject: [PATCH 2/2] fix Vale errors in troubleshooting docs --- modules/troubleshoot/pages/troubleshooting-che.adoc | 6 +++--- .../troubleshooting-workspace-startup-failures.adoc | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/modules/troubleshoot/pages/troubleshooting-che.adoc b/modules/troubleshoot/pages/troubleshooting-che.adoc index 16de823694..6dd67b1255 100644 --- a/modules/troubleshoot/pages/troubleshooting-che.adoc +++ b/modules/troubleshoot/pages/troubleshooting-che.adoc @@ -23,7 +23,7 @@ The first step for any problem is to check the Cloud Development Environment log | 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. +| Diagnose pod scheduling, image pull, {devworkspace}, and resource quota errors from the dashboard or the Operator logs. | Cloud Development Environment is slow | Identify configuration changes that reduce startup time and improve runtime performance. @@ -34,9 +34,9 @@ The first step for any problem is to check the Cloud Development Environment log | OAuth or Git authentication errors | Verify callback URLs, Secret labels, GitLab scopes, and Bitbucket public keys. -| Webview or editor UI errors +| Editor webview or UI errors | Fix service worker errors in private browsing windows. | Devfile syntax or validation errors | Diagnose component failures, lifecycle command problems, and volume or endpoint misconfigurations. -|=== \ No newline at end of file +|=== diff --git a/modules/troubleshoot/pages/troubleshooting-workspace-startup-failures.adoc b/modules/troubleshoot/pages/troubleshooting-workspace-startup-failures.adoc index 622896235e..498b5f2328 100644 --- a/modules/troubleshoot/pages/troubleshooting-workspace-startup-failures.adoc +++ b/modules/troubleshoot/pages/troubleshooting-workspace-startup-failures.adoc @@ -41,18 +41,18 @@ Diagnose and resolve common workspace startup failures based on error symptoms a | The container runtime does not trust the TLS certificate of the container registry. Import the registry Certificate Authority (CA) certificate into {prod-short}. |=== -== DevWorkspace errors +== {devworkspace} errors -.DevWorkspace error messages and resolutions +.{devworkspace} error messages and resolutions [cols="1,2",options="header"] |=== | Error message | Resolution -| `DevWorkspace failed to start: timed out waiting for DevWorkspace to be ready` +| `{devworkspace} failed to start: timed out waiting for {devworkspace} to be ready` | The workspace did not reach the `Running` phase within the configured timeout. Increase `startTimeoutSeconds` in the `CheCluster` Custom Resource or investigate Pod events for resource or scheduling issues. -| `Failed to create DevWorkspace: admission webhook denied the request` -| The {devworkspace} Operator webhook rejected the DevWorkspace. Verify that the {devworkspace} Operator is running and that CRDs are up to date. +| `Failed to create {devworkspace}: admission webhook denied the request` +| The {devworkspace} Operator webhook rejected the {devworkspace}. Verify that the {devworkspace} Operator is running and that CRDs are up to date. | `BadRequest` or `InfrastructureFailure` | An infrastructure-level error prevented workspace creation. Check the {devworkspace} Operator logs for details. @@ -66,7 +66,7 @@ Diagnose and resolve common workspace startup failures based on error symptoms a | Error message | Resolution | `exceeded quota` or `forbidden: exceeded quota` -| The user namespace has a ResourceQuota that prevents creating the workspace Pod or PVC. Increase the quota or reduce the workspace resource requests in the devfile. +| The user {namespace} has a ResourceQuota that prevents creating the workspace Pod or PVC. Increase the quota or reduce the workspace resource requests in the devfile. | `OOMKilled` | The workspace container exceeded its memory limit and was terminated. Increase the memory limit in the devfile `components` section or in the `CheCluster` Custom Resource defaults.