From e3f6186d85408740864134e06889a7b900ddbbab Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 10 Apr 2024 20:25:11 +0100 Subject: [PATCH 1/6] chore(docs): add support bundle guide --- docs/guides/support-bundle.md | 86 +++++++++++++++++++++++++++++++++++ docs/manifest.json | 5 ++ 2 files changed, 91 insertions(+) create mode 100644 docs/guides/support-bundle.md diff --git a/docs/guides/support-bundle.md b/docs/guides/support-bundle.md new file mode 100644 index 0000000000000..a46ab42c04570 --- /dev/null +++ b/docs/guides/support-bundle.md @@ -0,0 +1,86 @@ +# Generate and upload a Support Bundle to Coder Support + +When you engage with Coder support to diagnose an issue with your deployment, +you may be asked to generate and upload a "Support Bundle" for offline analysis. +This document explains the contents of a support bundle and the steps to submit +a support bundle to Coder staff. + +## What is a Support Bundle? + +A support bundle is an archive containing a snapshot of information about your +Coder deployment. + +It contains information about the workspace, the template it uses, running +agents in the workspace, and other detailed information useful for +troubleshooting. + +It is primarily intended for troubleshooting connectivity issues to workspaces, +but can be useful for diagnosing other issues as well. + +**While we attempt to redact sensitive information from support bundles, they +may contain information deemed sensitive by your organization and should be +treated as such.** + +A brief overview of all files contained in the bundle is provided below: + +> Note: detailed descriptions of all the information available in the bundle is +> out of scope, as support bundles are primarily intended for internal use. + +| Filename | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------ | +| `cli_logs.txt` | Logs from running the `coder support bundle` command. | +| `logs.txt` | Logs from the `codersdk.Client` used to generate the bundle. | +| `deployment/buildinfo.json` | Coder version and build information. | +| `deployment/config.json` | Deployment [configuration](../api/general.md#get-deployment-config), with secret values removed. | +| `deployment/experiments.json` | Any [experiments](../cli/server.md#experiments) currently enabled for the deployment. | +| `deployment/health.json` | A snapshot of the [health status](../admin/healthcheck.md) of the deployment. | +| `network/coordinator_debug.html` | Peers currently connected to each Coder instance and the tunnels established between peers. | +| `network/netcheck.json` | DERP regions available, their connection status, and capabilities (STUN, DERP, etc.). | +| `network/tailnet_debug.html` | Tailnet coordinators, their heartbeat ages, connected peers, and tunnels. | +| `workspace/build_logs.txt` | Build logs of the selected workspace. | +| `workspace/workspace.json` | Details of the selected workspace. | +| `workspace/parameters.json` | Build parameters of the selected workspace. | +| `workspace/template.json` | The template currently in use by the selected workspace. | +| `workspace/template_file.zip` | The source code of the template currently in use by the selected workspace. | +| `workspace/template_version.json` | The template version currently in use by the selected workspace. | +| `agent/agent.json` | The agent used to connect to the workspace with environment variables stripped. | +| `agent/agent_magicsock.html` | The contents of the HTTP debug endpoint of the agent's Tailscale connection. | +| `agent/client_magicsock.html` | The contents of the HTTP debug endpoint of the client's Tailscale connection. | +| `agent/listening_ports.json` | The listening ports detected by the selected agent running in the workspace. | +| `agent/logs.txt` | The logs of the selected agent running in the workspace. | +| `agent/manifest.json` | The manifest of the selected agent with environment variables stripped. | +| `agent/startup_logs.txt` | Startup logs of the workspace agent. | +| `agent/prometheus.txt` | The contents of the agent's Prometheus endpoint. | + +## How do I generate a Support Bundle? + +1. Ensure your deployment is up and running. Generating a support bundle + requires the Coder deployment to be available. + +2. Ensure you have the Coder CLI installed on a local machine. See + (installation)[../install/index.md] for steps on how to do this. + + > Note: It is recommended to generate a support bundle from a location + > experiencing workspace connectivity issues. + +3. Ensure you are [logged in](../cli/login.md#login) to your Coder deployment as + a user with the Owner privilege. + +4. Run `coder support bundle [owner/workspace]`, and respond `yes` to the + prompt. The support bundle will be generated in the current directory with + the filename `coder-support-$TIMESTAMP.zip`. + + > Note that generating a support bundle currently requires a running + > workspace to function. + +5. (Recommended) Extract the support bundle and review its contents, redacting + any information you deem necessary. + +6. Coder staff will provide you a link where you can upload the bundle along + with any other necessary supporting files. + + > Note: It is helpful to leave an informative message regarding the nature of + > supporting files. + +Coder support will then review the information you provided and respond to you +with next steps. diff --git a/docs/manifest.json b/docs/manifest.json index a7896946fe761..ad79589613b28 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1070,6 +1070,11 @@ "path": "./guides/index.md", "icon_path": "./images/icons/notes.svg", "children": [ + { + "title": "Generate a Support Bundle", + "description": "Generate and upload a Support Bundle to Coder Support", + "path": "./guides/support-bundle.md" + }, { "title": "Configuring Okta", "description": "Custom claims/scopes with Okta for group/role sync", From 19d3fa5406346686c8a92ab2fd6c2661d7809f18 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 10 Apr 2024 20:27:54 +0100 Subject: [PATCH 2/6] chore(cli): order map kvs in writeBundle for a e s t h e t i c s --- cli/support.go | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/cli/support.go b/cli/support.go index 2e87b0147942a..9ca4c9372f0a5 100644 --- a/cli/support.go +++ b/cli/support.go @@ -222,20 +222,20 @@ func findAgent(agentName string, haystack []codersdk.WorkspaceResource) (*coders func writeBundle(src *support.Bundle, dest *zip.Writer) error { // We JSON-encode the following: for k, v := range map[string]any{ - "deployment/buildinfo.json": src.Deployment.BuildInfo, - "deployment/config.json": src.Deployment.Config, - "deployment/experiments.json": src.Deployment.Experiments, - "deployment/health.json": src.Deployment.HealthReport, - "network/netcheck.json": src.Network.Netcheck, - "workspace/workspace.json": src.Workspace.Workspace, "agent/agent.json": src.Agent.Agent, "agent/listening_ports.json": src.Agent.ListeningPorts, "agent/manifest.json": src.Agent.Manifest, "agent/peer_diagnostics.json": src.Agent.PeerDiagnostics, "agent/ping_result.json": src.Agent.PingResult, + "deployment/buildinfo.json": src.Deployment.BuildInfo, + "deployment/config.json": src.Deployment.Config, + "deployment/experiments.json": src.Deployment.Experiments, + "deployment/health.json": src.Deployment.HealthReport, + "network/netcheck.json": src.Network.Netcheck, + "workspace/parameters.json": src.Workspace.Parameters, "workspace/template.json": src.Workspace.Template, "workspace/template_version.json": src.Workspace.TemplateVersion, - "workspace/parameters.json": src.Workspace.Parameters, + "workspace/workspace.json": src.Workspace.Workspace, } { f, err := dest.Create(k) if err != nil { @@ -255,17 +255,17 @@ func writeBundle(src *support.Bundle, dest *zip.Writer) error { // The below we just write as we have them: for k, v := range map[string]string{ - "network/coordinator_debug.html": src.Network.CoordinatorDebug, - "network/tailnet_debug.html": src.Network.TailnetDebug, - "workspace/build_logs.txt": humanizeBuildLogs(src.Workspace.BuildLogs), + "cli_logs.txt": string(src.CLILogs), + "logs.txt": strings.Join(src.Logs, "\n"), "agent/logs.txt": string(src.Agent.Logs), "agent/agent_magicsock.html": string(src.Agent.AgentMagicsockHTML), "agent/client_magicsock.html": string(src.Agent.ClientMagicsockHTML), "agent/startup_logs.txt": humanizeAgentLogs(src.Agent.StartupLogs), "agent/prometheus.txt": string(src.Agent.Prometheus), + "network/coordinator_debug.html": src.Network.CoordinatorDebug, + "network/tailnet_debug.html": src.Network.TailnetDebug, + "workspace/build_logs.txt": humanizeBuildLogs(src.Workspace.BuildLogs), "workspace/template_file.zip": string(templateVersionBytes), - "logs.txt": strings.Join(src.Logs, "\n"), - "cli_logs.txt": string(src.CLILogs), } { f, err := dest.Create(k) if err != nil { From 2ee66856d0e96f116bdf9bda6204a7c8dcd5bac9 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 12 Apr 2024 09:44:04 +0100 Subject: [PATCH 3/6] Revert "chore(cli): order map kvs in writeBundle for a e s t h e t i c s" This reverts commit 19d3fa5406346686c8a92ab2fd6c2661d7809f18. --- cli/support.go | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/cli/support.go b/cli/support.go index 9ca4c9372f0a5..2e87b0147942a 100644 --- a/cli/support.go +++ b/cli/support.go @@ -222,20 +222,20 @@ func findAgent(agentName string, haystack []codersdk.WorkspaceResource) (*coders func writeBundle(src *support.Bundle, dest *zip.Writer) error { // We JSON-encode the following: for k, v := range map[string]any{ - "agent/agent.json": src.Agent.Agent, - "agent/listening_ports.json": src.Agent.ListeningPorts, - "agent/manifest.json": src.Agent.Manifest, - "agent/peer_diagnostics.json": src.Agent.PeerDiagnostics, - "agent/ping_result.json": src.Agent.PingResult, "deployment/buildinfo.json": src.Deployment.BuildInfo, "deployment/config.json": src.Deployment.Config, "deployment/experiments.json": src.Deployment.Experiments, "deployment/health.json": src.Deployment.HealthReport, "network/netcheck.json": src.Network.Netcheck, - "workspace/parameters.json": src.Workspace.Parameters, + "workspace/workspace.json": src.Workspace.Workspace, + "agent/agent.json": src.Agent.Agent, + "agent/listening_ports.json": src.Agent.ListeningPorts, + "agent/manifest.json": src.Agent.Manifest, + "agent/peer_diagnostics.json": src.Agent.PeerDiagnostics, + "agent/ping_result.json": src.Agent.PingResult, "workspace/template.json": src.Workspace.Template, "workspace/template_version.json": src.Workspace.TemplateVersion, - "workspace/workspace.json": src.Workspace.Workspace, + "workspace/parameters.json": src.Workspace.Parameters, } { f, err := dest.Create(k) if err != nil { @@ -255,17 +255,17 @@ func writeBundle(src *support.Bundle, dest *zip.Writer) error { // The below we just write as we have them: for k, v := range map[string]string{ - "cli_logs.txt": string(src.CLILogs), - "logs.txt": strings.Join(src.Logs, "\n"), + "network/coordinator_debug.html": src.Network.CoordinatorDebug, + "network/tailnet_debug.html": src.Network.TailnetDebug, + "workspace/build_logs.txt": humanizeBuildLogs(src.Workspace.BuildLogs), "agent/logs.txt": string(src.Agent.Logs), "agent/agent_magicsock.html": string(src.Agent.AgentMagicsockHTML), "agent/client_magicsock.html": string(src.Agent.ClientMagicsockHTML), "agent/startup_logs.txt": humanizeAgentLogs(src.Agent.StartupLogs), "agent/prometheus.txt": string(src.Agent.Prometheus), - "network/coordinator_debug.html": src.Network.CoordinatorDebug, - "network/tailnet_debug.html": src.Network.TailnetDebug, - "workspace/build_logs.txt": humanizeBuildLogs(src.Workspace.BuildLogs), "workspace/template_file.zip": string(templateVersionBytes), + "logs.txt": strings.Join(src.Logs, "\n"), + "cli_logs.txt": string(src.CLILogs), } { f, err := dest.Create(k) if err != nil { From 72e7cd3ce3498204d129b3f12fba9c16ef804f4a Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 12 Apr 2024 09:51:57 +0100 Subject: [PATCH 4/6] fix after #12946 --- docs/guides/support-bundle.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/guides/support-bundle.md b/docs/guides/support-bundle.md index a46ab42c04570..209e07ba5a4bf 100644 --- a/docs/guides/support-bundle.md +++ b/docs/guides/support-bundle.md @@ -28,14 +28,23 @@ A brief overview of all files contained in the bundle is provided below: | Filename | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------ | -| `cli_logs.txt` | Logs from running the `coder support bundle` command. | -| `logs.txt` | Logs from the `codersdk.Client` used to generate the bundle. | +| `agent/agent.json` | The agent used to connect to the workspace with environment variables stripped. | +| `agent/agent_magicsock.html` | The contents of the HTTP debug endpoint of the agent's Tailscale connection. | +| `agent/client_magicsock.html` | The contents of the HTTP debug endpoint of the client's Tailscale connection. | +| `agent/listening_ports.json` | The listening ports detected by the selected agent running in the workspace. | +| `agent/logs.txt` | The logs of the selected agent running in the workspace. | +| `agent/manifest.json` | The manifest of the selected agent with environment variables stripped. | +| `agent/startup_logs.txt` | Startup logs of the workspace agent. | +| `agent/prometheus.txt` | The contents of the agent's Prometheus endpoint. | | `deployment/buildinfo.json` | Coder version and build information. | | `deployment/config.json` | Deployment [configuration](../api/general.md#get-deployment-config), with secret values removed. | | `deployment/experiments.json` | Any [experiments](../cli/server.md#experiments) currently enabled for the deployment. | | `deployment/health.json` | A snapshot of the [health status](../admin/healthcheck.md) of the deployment. | +| `cli_logs.txt` | Logs from running the `coder support bundle` command. | +| `logs.txt` | Logs from the `codersdk.Client` used to generate the bundle. | +| `network/connection_info.json` | Information used by workspace agents used to connect to Coder (DERP map etc.) | | `network/coordinator_debug.html` | Peers currently connected to each Coder instance and the tunnels established between peers. | -| `network/netcheck.json` | DERP regions available, their connection status, and capabilities (STUN, DERP, etc.). | +| `network/netcheck.json` | Results of running `coder netcheck` locally. | | `network/tailnet_debug.html` | Tailnet coordinators, their heartbeat ages, connected peers, and tunnels. | | `workspace/build_logs.txt` | Build logs of the selected workspace. | | `workspace/workspace.json` | Details of the selected workspace. | @@ -43,14 +52,6 @@ A brief overview of all files contained in the bundle is provided below: | `workspace/template.json` | The template currently in use by the selected workspace. | | `workspace/template_file.zip` | The source code of the template currently in use by the selected workspace. | | `workspace/template_version.json` | The template version currently in use by the selected workspace. | -| `agent/agent.json` | The agent used to connect to the workspace with environment variables stripped. | -| `agent/agent_magicsock.html` | The contents of the HTTP debug endpoint of the agent's Tailscale connection. | -| `agent/client_magicsock.html` | The contents of the HTTP debug endpoint of the client's Tailscale connection. | -| `agent/listening_ports.json` | The listening ports detected by the selected agent running in the workspace. | -| `agent/logs.txt` | The logs of the selected agent running in the workspace. | -| `agent/manifest.json` | The manifest of the selected agent with environment variables stripped. | -| `agent/startup_logs.txt` | Startup logs of the workspace agent. | -| `agent/prometheus.txt` | The contents of the agent's Prometheus endpoint. | ## How do I generate a Support Bundle? From eab8f7510db018654fd826e5f8616b08003046a9 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 12 Apr 2024 09:52:29 +0100 Subject: [PATCH 5/6] fixup! fix after #12946 --- docs/guides/support-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/support-bundle.md b/docs/guides/support-bundle.md index 209e07ba5a4bf..ba9d659bcdab4 100644 --- a/docs/guides/support-bundle.md +++ b/docs/guides/support-bundle.md @@ -36,11 +36,11 @@ A brief overview of all files contained in the bundle is provided below: | `agent/manifest.json` | The manifest of the selected agent with environment variables stripped. | | `agent/startup_logs.txt` | Startup logs of the workspace agent. | | `agent/prometheus.txt` | The contents of the agent's Prometheus endpoint. | +| `cli_logs.txt` | Logs from running the `coder support bundle` command. | | `deployment/buildinfo.json` | Coder version and build information. | | `deployment/config.json` | Deployment [configuration](../api/general.md#get-deployment-config), with secret values removed. | | `deployment/experiments.json` | Any [experiments](../cli/server.md#experiments) currently enabled for the deployment. | | `deployment/health.json` | A snapshot of the [health status](../admin/healthcheck.md) of the deployment. | -| `cli_logs.txt` | Logs from running the `coder support bundle` command. | | `logs.txt` | Logs from the `codersdk.Client` used to generate the bundle. | | `network/connection_info.json` | Information used by workspace agents used to connect to Coder (DERP map etc.) | | `network/coordinator_debug.html` | Peers currently connected to each Coder instance and the tunnels established between peers. | From 9a7d84db65f66f392ccd6db2f7e72283d5bdd1b9 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 12 Apr 2024 09:54:37 +0100 Subject: [PATCH 6/6] modify note about needing a workspace --- docs/guides/support-bundle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/support-bundle.md b/docs/guides/support-bundle.md index ba9d659bcdab4..9b2d8ec52cc97 100644 --- a/docs/guides/support-bundle.md +++ b/docs/guides/support-bundle.md @@ -71,8 +71,8 @@ A brief overview of all files contained in the bundle is provided below: prompt. The support bundle will be generated in the current directory with the filename `coder-support-$TIMESTAMP.zip`. - > Note that generating a support bundle currently requires a running - > workspace to function. + > While support bundles can be generated without a running workspace, it is + > recommended to specify one to maximize troubleshooting information. 5. (Recommended) Extract the support bundle and review its contents, redacting any information you deem necessary.