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..6dd67b1255 100644 --- a/modules/troubleshoot/pages/troubleshooting-che.adoc +++ b/modules/troubleshoot/pages/troubleshooting-che.adoc @@ -19,8 +19,11 @@ 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. +| 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. @@ -31,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 beb4fe10cf..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. @@ -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[]