From 0ee21af3c10c4d02e67978d01f0405520d1a3296 Mon Sep 17 00:00:00 2001 From: Alona King Date: Mon, 24 Aug 2026 14:12:06 -0400 Subject: [PATCH] docs: add enterprise troubleshooting guide --- docs.json | 3 +- enterprise/k8s-install/installation.mdx | 7 +- enterprise/quick-start.mdx | 8 +- enterprise/troubleshooting.mdx | 207 ++++++++++++++++++ .../admin-console-configuration.mdx | 6 + 5 files changed, 225 insertions(+), 6 deletions(-) create mode 100644 enterprise/troubleshooting.mdx diff --git a/docs.json b/docs.json index 8fe0cf8eb..08250f229 100644 --- a/docs.json +++ b/docs.json @@ -524,7 +524,8 @@ "enterprise/quick-start", "enterprise/custom-sandbox-image", "enterprise/docker-in-sandbox", - "enterprise/external-postgres" + "enterprise/external-postgres", + "enterprise/troubleshooting" ] }, { diff --git a/enterprise/k8s-install/installation.mdx b/enterprise/k8s-install/installation.mdx index cd4e8cf16..a3d811975 100644 --- a/enterprise/k8s-install/installation.mdx +++ b/enterprise/k8s-install/installation.mdx @@ -290,6 +290,9 @@ overrides on the same release — edit your `values.yaml` and apply with ## Troubleshooting +For a guided diagnostic workflow and a map of OHE components, see +[Troubleshooting](/enterprise/troubleshooting). + ### Generate a support bundle If something isn't working, generate a support bundle with the @@ -298,7 +301,7 @@ It discovers the diagnostic specs that ship with the chart and collects logs, resource states, and health checks from the installation: ```bash -support-bundle --load-cluster-specs --namespace openhands +kubectl support-bundle --load-cluster-specs --namespace openhands ``` ### Send it to us @@ -307,7 +310,7 @@ Upload the resulting archive directly to our support team — the upload authenticates with the license embedded in the bundle: ```bash -support-bundle upload support-bundle-.tar.gz +kubectl support-bundle upload support-bundle-.tar.gz ``` ### Common issues diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 5e108e608..31ccdc645 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -286,7 +286,9 @@ The install guide provides commands to run on your VM. SSH into your VM and exec 3. **Extract the installation assets** -- run the `tar` command shown (this includes your license file) 4. **Install** -- run the install command shown -If the install command fails after preflight checks pass, run `sudo ./openhands support-bundle` and share the resulting bundle with support. +If the install command fails after preflight checks pass, see +[Troubleshooting](/enterprise/troubleshooting) to generate a support +bundle and open a support ticket. **We recommend providing your TLS certificates during installation.** If you used the @@ -443,8 +445,8 @@ OpenHands Enterprise is now running. You can open a repository or start a new co Get the most out of your AI coding agents with effective prompting techniques. - - Reach out to the OpenHands team for deployment assistance or questions. + + Collect diagnostics, inspect workloads, and contact OpenHands Support. Explore the full OpenHands documentation for usage guides and features. diff --git a/enterprise/troubleshooting.mdx b/enterprise/troubleshooting.mdx new file mode 100644 index 000000000..157557616 --- /dev/null +++ b/enterprise/troubleshooting.mdx @@ -0,0 +1,207 @@ +--- +title: Troubleshooting +description: Collect diagnostics and inspect OpenHands Enterprise (OHE) workloads. +icon: life-ring +--- + +OpenHands Enterprise Replicated VM installations run in a Replicated Embedded +Cluster which is a Kubernetes cluster based on k0s. Once you have access to the +VM, you can use standard Kubernetes commands to inspect OHE. For Helm +deployments, use your existing Kubernetes access to run the same commands. + +Most OHE workloads run in the `openhands` namespace. The Replicated Admin +Console runs in `kotsadm`, and ingress runs in `traefik`. + +## Start With a Support Bundle + +A support bundle is the fastest way to give OpenHands Support a snapshot of the +installation. You do not need to investigate the problem yourself before opening +a support ticket. + +### Use the Admin Console + +For a Replicated VM installation: + +1. Open `https://admin.:30000`. +2. Select `Troubleshoot`. +3. Select `Analyze` and wait for it to finish. +4. Select `Download bundle`. + +If `Send bundle to vendor` is available, you can upload the bundle for us to +inspect directly. Sending a support bundle does not automatically create a +support ticket, so be sure to still open a support ticket and mention the +support bundle upload. + +### Use the Command Line + +On a Replicated VM, use the command line when the Admin Console is unavailable. +For a Helm installation, run the Kubernetes command from a workstation with +`kubectl` access. + + + + Connect to the VM and run: + + ```bash + sudo /var/lib/embedded-cluster/bin/openhands support-bundle + ``` + + If the installation did not complete, run the original installer from the + directory where you extracted it: + + ```bash + sudo ./openhands support-bundle + ``` + + + For OHE installed with Helm in an existing Kubernetes cluster, run this + command from a workstation with `kubectl` access: + + ```bash + kubectl support-bundle --load-cluster-specs --namespace openhands + ``` + + See the [Kubernetes installation guide](/enterprise/k8s-install/installation#step-5-validate-the-installation) + if the `support-bundle` CLI is not installed. + + + +The bundle includes cluster health, Kubernetes resource state, application logs, +and OHE service checks. + +### Open a Support Ticket + +Open the OpenHands Support Portal provided during Enterprise onboarding. Please +attach the generated archive. If you used `Send bundle to vendor`, mention the +upload in the ticket. Include: + +- When the problem occurred, including the time zone. +- The affected user or conversation ID, when applicable. +- The expected and actual behavior. +- Any recent upgrade or configuration change. +- Steps that reproduce the problem. + +If you cannot access the Support Portal, please contact your OpenHands +representative for more assistance. + +## Inspect the Deployment + +This workflow is for practitioners who are already familiar with `kubectl`. + + + Keep your investigation read-only. Do not change Kubernetes resources unless + directed by OpenHands Support. Ad hoc `kubectl` changes can be overwritten + during a deployment or upgrade and may leave the installation in an + inconsistent state. + + +### Get a Kubernetes Session + + + + Connect to a controller VM. On a single-node installation, this is the OHE + VM. Then run: + + ```bash + sudo /var/lib/embedded-cluster/bin/openhands shell + ``` + + This opens a shell with `kubectl` configured for the embedded cluster. Run + `exit` when finished. + + + Use your existing Kubernetes access and confirm the current context: + + ```bash + kubectl config current-context + kubectl get pods -n openhands + ``` + + + +### Check Overall Status + +Record the time, then inspect the cluster and recent events: + +```bash +date -u +kubectl get nodes -o wide +kubectl get pods -n openhands -o wide +kubectl get deployments,statefulsets -n openhands +kubectl get events -n openhands --sort-by=.metadata.creationTimestamp +``` + +Start with the `STATUS`, `READY`, and `RESTARTS` columns: + +- `Pending` usually points to scheduling, storage, or capacity problems. +- `Init:` means an init container has not completed. Check that container's logs. +- `CrashLoopBackOff` means a container repeatedly exits. Check previous logs. +- A pod that is not ready or keeps restarting usually has a failed dependency, + health check, or resource limit. + +If the Kubernetes Metrics API is available, check current resource usage: + +```bash +kubectl top pods -n openhands +``` + +### Inspect a Pod and Its Logs + +```bash +kubectl describe pod -n openhands + +kubectl logs -n openhands \ + --all-containers=true --since=30m --timestamps + +kubectl logs -n openhands \ + --all-containers=true --previous --timestamps + +kubectl logs -n openhands -c \ + --since=10m --timestamps --follow +``` + +Use `--previous` after a container restarts. Use `-c` to select a specific +container, including an init container such as `migrate-db`. + +### Choose the Right Component + +Pod names may include a release prefix and generated suffix. Match the +recognizable component name to the table below. + +| Component | Investigate when | +|---|---| +| `openhands` | Web application, API, conversations, and general application errors. | +| `openhands-integrations` | Integration events and background integration work. | +| `runtime-api` | Sandbox creation, startup, pause, and cleanup. | +| `runtime-...` | A particular conversation's sandbox. | +| `litellm` | Model-provider requests and authentication. | +| `keycloak` | Login, SSO, and authentication. | +| `kotsadm` namespace | Replicated Admin Console problems. | + +### Temporarily Enable Debug Logging + +On a Replicated VM, `Log Level` defaults to `INFO`. Use `DEBUG` only during a +short investigation: + +1. In the Admin Console, select `Config`. +2. Under `Troubleshooting`, set `Log Level` to `DEBUG`. +3. Save and deploy, then reproduce the problem. +4. Collect the logs or a support bundle. +5. Return `Log Level` to `INFO`, then save and deploy again. + +## Related Guides + + + + Install an OpenHands Enterprise VM deployment. + + + Configure a Replicated VM installation. + + + Install OHE into an existing Kubernetes cluster. + + + Diagnose and tune CPU, memory, replicas, and storage. + + diff --git a/enterprise/vm-install/admin-console-configuration.mdx b/enterprise/vm-install/admin-console-configuration.mdx index 88cbcd084..eca4a45f2 100644 --- a/enterprise/vm-install/admin-console-configuration.mdx +++ b/enterprise/vm-install/admin-console-configuration.mdx @@ -252,6 +252,9 @@ Prefer adding the proxy CA under `Additional Trusted CA Certificates` instead of `Log Level` defaults to `INFO`. Use `DEBUG` only while investigating a problem because it produces significantly more log output. Return to `INFO` after collecting the necessary diagnostics. +See [Troubleshooting](/enterprise/troubleshooting) to generate a +support bundle, inspect component logs, and open a support ticket. + ## Experimental `Enable Plugin Directory` deploys the experimental plugin marketplace at `/plugins`. When enabled, configure a marketplace source beginning with `github://`, `https://`, or `http://`. @@ -307,4 +310,7 @@ Replicated generates internal PostgreSQL, Redis, JWT, Keycloak, LiteLLM, sandbox Configure Laminar observability. + + Collect diagnostics and inspect the deployment. +