🤖 feat: complete the workspace pool how-to (#153 PR 16b)

docs/how-to/gitops.md

@@ -231,9 +231,9 @@ Add this entry (`config/gitops/flux-healthcheck-coderaiprovider.yaml`) to `spec.
 
 ## Health rules for CoderWorkspacePool and CoderWorkspaceClaim
 
-Argo CD and Flux also need health rules to wait for a [workspace pool](workspace-pools.md) and its claims. Without them, Argo CD has no health check for the kinds, and Flux reports a new pool or claim as current before the controller writes its first status. The controller writes the conditions `Ready`, `Reconciling` and `Stalled` of a pool or a claim together, with one reason and message, and with the object's `metadata.generation` as the condition's `observedGeneration`. The rules ignore a condition whose `observedGeneration` is older.
+Argo CD and Flux also need health rules to wait for a [workspace pool](workspace-pools.md) and its claims. Without them, Argo CD has no health check for the kinds, and Flux reports a new pool or claim as current before the controller writes its first status. The controller writes the conditions `Ready`, `Reconciling` and `Stalled` of a pool or a claim together, with one reason and message, and with the object's `metadata.generation` as the condition's `observedGeneration`. The Argo CD rules ignore each condition whose `observedGeneration` is older. The Flux rules wait for a `Ready` condition of the current generation, and then read the conditions without that filter. The controller gives all three conditions one generation, so both rules agree on what it writes.
 
-A pool also has `status.observedGeneration`, and both pool rules wait until it equals `metadata.generation`. Every `/scale` write raises the generation, so after `kubectl scale`, or a resize by an HPA or KEDA, the pool shows `Progressing` until the controller has counted its members for the new `spec.replicas`.
+A pool also has `status.observedGeneration`, and both pool rules wait until it equals `metadata.generation`. A change of `spec.replicas` through `/scale` raises the generation, so after `kubectl scale`, or a resize by an HPA or KEDA, the pool shows `Progressing` until the controller has counted its members for the new `spec.replicas`.
 
 | Pool conditions | Argo CD | Flux |
 | --- | --- | --- |

docs/how-to/troubleshooting.md

@@ -316,7 +316,7 @@ kubectl get coderworkspacepools,coderworkspacepoolmembers,coderworkspaceclaims -
 kubectl get coderworkspacepoolmember <name> -n <namespace> -o jsonpath='{.status.reason}: {.status.message}{"\n"}'
 ```
 
-A wait ends by itself when its cause goes away. A failure is final for a member: its phase becomes `Failed`. The pool deletes a failed unclaimed member and creates a new one. A claimed member that fails stays, and its claim stays `Bound` and not ready until you delete the claim. If its workspace is gone, the claim becomes `Lost` instead. A failure of the pool sets `Stalled=True`. The pool reads Coder again every 60 s, also while it is stalled, so a fix in Coder ends a stall without a spec change. A claim often does not show why its pool cannot create workspaces. If a claim waits for a long time, read the reason of its pool.
+A wait ends by itself when its cause goes away. A failure is final for a member: its phase becomes `Failed`. The pool deletes a failed unclaimed member and creates a new one. A claimed member that fails stays, and its claim stays `Bound` and not ready until you delete the claim. If its workspace is gone, the claim becomes `Lost` instead. A failure of the pool sets `Stalled=True`. A stalled pool reads Coder again every 60 s, so a fix in Coder ends the stall without a spec change. A claim often does not show why its pool cannot create workspaces. If a claim waits for a long time, read the reason of its pool.
 
 ### Reasons of a pool and of a member before its create request
 
@@ -366,7 +366,7 @@ The pool checks its inputs in Coder, and each member checks them again right bef
 | `WorkspaceReady` | ready | Every agent is ready. A claim can take the workspace. | None. |
 | `Used` | wait | The workspace's `last_used_at` moved after it became ready, so someone used it without a claim, or Coder counted something else as a use. Opening the workspace's page in the Coder dashboard counts ([#444](https://github.com/coder/coder-k8s/issues/444)). The member gets `Used=True`, and the pool releases it. | See [Cleanup](workspace-pools.md#cleanup). |
 | `AgentNotReady` | wait | An agent of a ready workspace disconnected or is no longer ready. No claim takes the workspace meanwhile. A failed Coder read keeps this reason, and the 5 min keep counting. | None, unless it becomes `AgentLost`. |
-| `AgentLost` | failure | An agent stayed not ready for 5 min. | Read the agent logs in Coder. |
+| `AgentLost` | failure | An agent stayed not ready for 5 min. While Coder is unreachable, the member waits. A failed read keeps `AgentNotReady` and its 5 min. `AgentLost` comes with the first successful read after the 5 min, if the agent is still not ready. | Read the agent logs in Coder. |
 | `ChangedExternally` | failure | Someone else started a build of the workspace, for example a stop, an update, or Coder's autostop. | None. The pool replaces an unclaimed member. |
 | `Dormant` | failure | Coder marked the workspace dormant, or scheduled its deletion. | Check the template's dormancy settings. |
 | `MaxDeadline` | wait | The workspace's max deadline allows no extension of its autostop deadline. Coder stops the workspace at the max deadline, and the pool replaces it. | None. |
@@ -412,7 +412,7 @@ After `ShareRevoked` or `ShareRemoved`, Coder no longer lists the user on the wo
 
 ### The pool owner is dormant
 
-The pool waits with `OwnerNotEligible`, and the message names the status `dormant`. Coder creates users through its API as `dormant`, and every 15 minutes it marks each active user dormant whose last login or API use is older than 90 days. An activation does not count as a use. Activate the owner in Coder, then log in as it once, for example with `POST /api/v2/users/login`. After that, use the owner's credentials at least once every 90 days. The pool deletes its unclaimed workspaces while the owner is not eligible, and builds new ones once the owner is active.
+The pool waits with `OwnerNotEligible`, and the message names the status `dormant`. Coder creates users through its API as `dormant`, unless the create request sets another status. Every 15 minutes, Coder marks each active user dormant whose last login or API use is older than 90 days. An activation does not count as a use. Activate the owner in Coder, then send one request with the owner's credentials, for example a password login with `POST /api/v2/users/login`. A service account cannot log in: send a request such as `GET /api/v2/users/me` with its API token instead. After that, use the owner's credentials at least once every 90 days. The pool deletes its unclaimed workspaces while the owner is not eligible, and builds new ones once the owner is active.
 
 ### A claim stays `Pending` and names a member