[ThomasK33]

Summary

The workspace pool how-to is now the complete guide that plan row 16 of #153 asks for. It adds a section on autoscaling (kubectl scale, HPA, KEDA scale to zero, and GitOps with an autoscaler), a cleanup table with one row per case, security notes, a link to troubleshooting, and the #451 warning for kept Share workspaces. This is plan PR 16b, the last PR of #153. PR 16a (#453) added the GitOps health rules and the troubleshooting section.

Background

The how-to grew one PR at a time. Autoscaling had one paragraph inside "Create a pool", cleanup was four bullets, and threat notes were spread over several sections. Plan row 16 asks for autoscaling recipes, cost, cleanup behavior per case, and threat notes in one guide. #153 can close only when every item of the issue and every plan row is on main or is a tracked follow-up issue (checklist below).

Implementation

Most changes are in docs/how-to/workspace-pools.md. Steps 1 to 6 keep their headings, so existing links stay valid.

1. Step 3 points to the new "Autoscale a pool" section. That section takes over the kubectl scale example and 🤖 tests: pool Kind phases P10 to P12: scale to 0, KEDA cron autoscaling, active-version rollout (#153 PR 15b) #452's autoscaler paragraph with its Kind result. It also explains:
   • an HPA example with an External metric and the target type AverageValue, and why a Value target fails on the pool's selector,
   • why HPA stops at 1, and why KEDA reaches 0 (cooldownPeriod is 300 s by default), with a cron ScaledObject like the one that the Kind test runs,
   • GitOps with an autoscaler: leave spec.replicas out of Git, or use Argo CD ignoreDifferences together with RespectIgnoreDifferences=true (without that option, Argo CD writes the field back at each sync).
2. Step 6 gets the 🤖 CoderWorkspacePool Share mode: an idle-reaped workspace that the pool keeps stays shared without policy checks #451 warning: when idle reaping keeps a Share workspace, the workspace stays shared without policy checks. The admin removes the user from the workspace's sharing settings in Coder, which keeps the work.
3. Cost says that maxWorkspaces counts per control plane (moved from the Share warning, because it holds for every mode), and links 🤖 perf: pool members read GET /api/v2/users/me on every workspace read, doubling the request budget #443.
4. Cleanup is a table: deleting a claim, a pool, or the namespace, lowering replicas, changing inputs, losing consent, idle reaping, a used member, a renamed kwp- workspace, and deleting the control plane. It ends with the kwp- audit. The namespace row adds that the control plane in that namespace is deleted too, so members that have not deleted their workspaces yet release without a Coder call.
5. Security notes collect the owner token, plain-text parameters, RBAC, status hygiene (🤖 CoderWorkspaceClaim Share mode: claim reasons reveal facts about named Coder users #449), Share trust, and operator token transport.
6. A Troubleshooting section links to the section from 🤖 feat: GitOps health rules and troubleshooting for workspace pools (#153 PR 16a) #453.
7. Step 4's idle reaping warning now says that last_used_at is best-effort (plan section 16, line 783(d)), and step 3 points to it for Used. Coder v2.37.3 drops a batch of last_used_at updates when its database write fails (coderd/workspacestats/tracker.go, flush clears the set before the write, every 60 s by default).
8. The AgentLost row in troubleshooting.md now says that while Coder is unreachable, the member waits: a failed read keeps AgentNotReady and its 5 min, and AgentLost comes with the first successful read after the 5 min (behavior from 🤖 fix: bound a stored bind target, and keep AgentNotReady across failed reads (#153 plan section 16) #464, wording from its verifier).
9. Four wording fixes from the independent verifier of 🤖 feat: GitOps health rules and troubleshooting for workspace pools (#153 PR 16a) #453 also change troubleshooting.md and gitops.md:
   • Coder creates API users as dormant only by default. One request with the owner's credentials counts as a use, for example a password login, or an API token request for a service account, which cannot log in. Step 1 of the how-to says the same.
   • The troubleshooting intro now promises the 60 s re-read of Coder only for a stalled pool. A ready pool with a pinned version does not poll.
   • Only a change of spec.replicas raises the generation.
   • The Argo CD rules filter each condition by generation, and the Flux rules check the Ready condition's generation.

#153 closure checklist

Issue items:

• Goal, a pool with a scale subresource for kubectl scale, HPA, and KEDA: CoderWorkspacePool (Design B), activated in 🤖 feat: activate CoderWorkspacePool, CoderWorkspacePoolMember, and CoderWorkspaceClaim (#153 PR 12) #441. KEDA is tested in Kind in 🤖 tests: pool Kind phases P10 to P12: scale to 0, KEDA cron autoscaling, active-version rollout (#153 PR 15b) #452.
• Feasibility gate for Coder prebuilds: recorded as blocked upstream in CoderWorkspacePool: prebuilt workspaces with a scale subresource #153 (comment).
• "Prebuilds are a Premium feature; the controller must check the license": Design B needs no license. The license check belongs to strategy: Prebuilds, tracked in 🤖 CoderWorkspacePool: strategy Prebuilds after an upstream per-preset count API #459.

Plan rows (workspace-13.md section 11):

Row	Scope	PRs
1	Fake Coder routes	#243
2	Refactor 1: shared owner and template lookups	#250
3	Refactor 2: shared workspace steps	#255
4	CoderWorkspacePool types	#261
4b	CoderControlPlane.spec.workspacePools	#270
5	Member and claim types	#278, #279
6	Member checks and create request	#300, #301
7	Confirm, readiness, keep warm	#322, #324
8	Bind extension, watch rules, delete	#339, #343, #344
9	Pool resolve and creation under the caps	#357, #359
10	Failure runs, owner cap, delete order	#364, #379, #380
11	Claims	#387, #388
12	Activation (with #430, #433, #435, #436, #438 before it)	#441
13	Kind phases P6 to P8 and offline stubs	#445
14	Share mode	#446
15	Refresh and idle reaping, Kind phases P10 to P12 with KEDA	#447, #452
16	Health rules and troubleshooting, then this how-to	#453, this PR

Earlier plan section 16 entries that the #463 verifier found open:

Plan section 16 entry	Status
Line 783(c): a failed Coder read must not reset the AgentLost timer of a member with AgentNotReady	Fixed in #464 (merged 8296834)
Line 783(d): the docs must say that last_used_at is best-effort	This PR: the idle reaping warning in step 4, and step 3 for Used
Line 777(c): the bound and used counts check the member's owner against the pool's resolved owner	Tracked in #465
Line 785: bound the stored status.bindExtendDeadline to a fresh now + max(template default TTL, 30 min) before use (status.lastExtendTime no longer decides an extension)	Fixed in #464 (merged 8296834)

Deferred items (plan section 16), one tracked issue each: #455 (per-user pools), #456 (owner token in a Secret), #457 (Prometheus metrics), #458 (retain for members), #459 (strategy: Prebuilds), #460 (claim wait timeout), #461 (dedicated provisioner recipe), #462 (shipped admission policy).

Open follow-ups from the stack: #443, #444, #448, #449, #450, #451, #454.

Validation

• An independent reviewer compared the new text with the code before I opened this PR. It found 6 claims to correct, and I fixed them in the last commit. For example, a scale-down keeps the workspaces for waiting claims, and a Share claim must be fully deleted before the control plane is. I also checked each new claim against the controller code, the Kind phases of 🤖 feat: pool Kind phases P6 to P8, offline stubs for every phase, and deleting a released used member deletes its workspace (#153 PR 13) #445 and 🤖 tests: pool Kind phases P10 to P12: scale to 0, KEDA cron autoscaling, active-version rollout (#153 PR 15b) #452, the plan's Kubernetes and KEDA source references, and the Argo CD sync options docs.
• Local gates: make verify-vendor, make build, make lint, make test, nix develop -c make docs-check, markdownlint-cli2 "docs/**/*.md", and cspell with the CI versions.
• Dogfood: I ran make docs-serve and took agent-browser screenshots of the new sections at 390 px and 1440 px. They are in a comment below.

Risks

• Docs only.
• Kind does not run the HPA example. It follows the Kubernetes rules in plan sections 7.1 and 7.2, and Kind tests the HPA that KEDA makes.

Fixes #153

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: xhigh

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-01T06:26:32.491395Z	6e527b0	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ThomasK33]

Dogfood for plan row 16: nix develop -c make docs-serve on head 9467893, then agent-browser screenshots of the new how-to sections.

Desktop (1440 px):

Mobile (390 px). The cleanup table scrolls sideways, like the other tables on the site:

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9467893451

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

Both findings are fixed in fa794ec. The Autoscale section now says that the CRD refuses a /scale value above 100 (it does not cap it), and that HPA maxReplicas and ScaledObject maxReplicaCount must be 100 or less. The scale-down row now says that the pool keeps the new value plus one unclaimed workspace for each waiting claim. Claims are never deleted.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: fa794ecb0b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

New commit: step 4's idle reaping warning now says that last_used_at is best-effort. With Coder's workspace-usage experiment, connections without a session, such as a port-forward or another raw tunnel, do not move it, and a failed database flush drops a batch (Coder v2.37.3 coderd/workspacestats/reporter.go and tracker.go). Step 3 points to that warning for Used. The scale-down row now says "each waiting claim that can bind".

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: 4cbd2415f6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

Rebased on main 8296834 (#464). New commit 166ec59: the AgentLost row in troubleshooting.md now says that while Coder is unreachable, the member waits. A failed read keeps AgentNotReady and its 5 min (poolMemberKeepAgentNotReady from #464), and AgentLost comes with the first successful read after the 5 min, if the agent is still not ready.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 166ec5941c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

New commit 6e527b0 removes a wrong claim from step 4's idle reaping warning. Coder v2.37.3's agent stats path calls ReportAgentStats(..., false) even under the workspace-usage experiment, so any nonzero ConnectionCount (a port-forward included) moves last_used_at. The warning now keeps only the confirmed case: a failed database flush drops a batch of updates.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 6e527b0c46

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".