From 90c4d5d28abeb0b16a456d280dccd0cee4c9028c Mon Sep 17 00:00:00 2001
From: Mathias Fredriksson <mafredri@gmail.com>
Date: Fri, 27 Jan 2023 22:23:47 +0200
Subject: [PATCH] docs: Document agent readiness issues (startup script)
 (#5877)

Refs: #5749, #5851
---
 docs/templates.md | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/docs/templates.md b/docs/templates.md
index 1c8a214835..f63231512a 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 connection from [agent]...
 ```
 
 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,37 @@ practices:
   - The Coder agent startup script logs are typically stored in
     `/tmp/coder-startup-script.log`
 
+### Agent does not become ready
+
+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 become ready...
+```
+
+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 is taking longer than expected to get
+   ready, the agent startup script is still executing.
+   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" {
+  # ...
+  login_before_ready = false
+  startup_script_timeout  = 1800 # 30 minutes in seconds.
+}
+```
+
 ## Template permissions (enterprise)
 
 Template permissions can be used to give users and groups access to specific