From 39b78d7db3cd3b41de159003259383142d1d79e4 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Thu, 26 Jan 2023 17:31:11 +0000 Subject: [PATCH 1/3] docs: Document agent startup (script) issues Refs: #5749, #5851 --- docs/templates.md | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/templates.md b/docs/templates.md index 1c8a214835edd..dc6a86dbb1567 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -375,18 +375,23 @@ customize them however you like. ## Troubleshooting templates Occasionally, you may run into scenarios where a workspace is created, but the -agent is not connected. This means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts) +agent is either not connected or the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) +has failed or timed out. + +### Agent connection issues + +If the agent is not connected, it means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts) has failed on the resource. ```console $ coder ssh myworkspace -Waiting for [agent] to connect... +⢄⡱ Waiting for [agent] to connect... ``` While troubleshooting steps vary by resource, here are some general best practices: -- Ensure the resource has `curl` installed +- Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`) - Ensure the resource can `curl` your Coder [access URL](./admin/configure.md#access-url) - Manually connect to the resource and check the agent logs (e.g., `kubectl exec`, `docker exec` or AWS console) @@ -394,6 +399,36 @@ practices: - The Coder agent startup script logs are typically stored in `/tmp/coder-startup-script.log` +### Agent startup issues + +If the agent does not start, it means the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is still running or has exited with a non-zero status. This also means the [delay login until ready](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#delay_login_until_ready) option is enabled. + +```console +$ coder ssh myworkspace +⢄⡱ Waiting for [agent] to finish starting up... +``` + +To troubleshoot startup issues, check the agent logs as suggested above. For startup issues you can connect to the workspace using SSH with the `--no-wait` flag. + +```console +$ coder ssh myworkspace --no-wait + + > The workspace agent is taking longer than expected to + start. See troubleshooting instructions at: [...] + +user@myworkspace $ +``` + +If the startup script is expected to take a long time, you can try raising the timeout defined in the template: + +```tf +resource "coder_agent" "main" { + # ... + delay_login_until_ready = true + startup_script_timeout = 1800 # 30 minutes in seconds. +} +``` + ## Template permissions (enterprise) Template permissions can be used to give users and groups access to specific From 53b3038f6d9a101bf455ffdcda956a494ad1fe39 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Thu, 26 Jan 2023 17:35:54 +0000 Subject: [PATCH 2/3] fixup! docs: Document agent startup (script) issues --- docs/templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/templates.md b/docs/templates.md index dc6a86dbb1567..a4acac6f28106 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -408,7 +408,7 @@ $ coder ssh myworkspace ⢄⡱ Waiting for [agent] to finish starting up... ``` -To troubleshoot startup issues, check the agent logs as suggested above. For startup issues you can connect to the workspace using SSH with the `--no-wait` flag. +To troubleshoot startup issues, check the agent logs as suggested above. For startup issues you can connect to the workspace using SSH with the `--no-wait` flag. Please note that while this makes login possible, the workspace may be in an incomplete state. ```console $ coder ssh myworkspace --no-wait From c3f75d586964d2a5e439a08e13296b08028e6d0b Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Fri, 27 Jan 2023 18:43:54 +0000 Subject: [PATCH 3/3] Update docs to align with #5893 --- docs/templates.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/templates.md b/docs/templates.md index a4acac6f28106..f63231512abf0 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -385,7 +385,7 @@ has failed on the resource. ```console $ coder ssh myworkspace -⢄⡱ Waiting for [agent] to connect... +⢄⡱ Waiting for connection from [agent]... ``` While troubleshooting steps vary by resource, here are some general best @@ -399,22 +399,23 @@ practices: - The Coder agent startup script logs are typically stored in `/tmp/coder-startup-script.log` -### Agent startup issues +### Agent does not become ready -If the agent does not start, it means the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is still running or has exited with a non-zero status. This also means the [delay login until ready](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#delay_login_until_ready) option is enabled. +If the agent does not become ready, it means the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is still running or has exited with a non-zero status. This also means the [login before ready](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#login_before_ready) option hasn't been set to true. ```console $ coder ssh myworkspace -⢄⡱ Waiting for [agent] to finish starting up... +⢄⡱ Waiting for [agent] to become ready... ``` -To troubleshoot startup issues, check the agent logs as suggested above. For startup issues you can connect to the workspace using SSH with the `--no-wait` flag. Please note that while this makes login possible, the workspace may be in an incomplete state. +To troubleshoot readiness issues, check the agent logs as suggested above. You can connect to the workspace using `coder ssh` with the `--no-wait` flag. Please note that while this makes login possible, the workspace may be in an incomplete state. ```console $ coder ssh myworkspace --no-wait - > The workspace agent is taking longer than expected to - start. See troubleshooting instructions at: [...] + > The workspace is taking longer than expected to get + ready, the agent startup script is still executing. + See troubleshooting instructions at: [...] user@myworkspace $ ``` @@ -424,7 +425,7 @@ If the startup script is expected to take a long time, you can try raising the t ```tf resource "coder_agent" "main" { # ... - delay_login_until_ready = true + login_before_ready = false startup_script_timeout = 1800 # 30 minutes in seconds. } ```