From 261af65aba523a492f91b34627d5ae3d24c1099a Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Thu, 24 Sep 2026 11:00:24 +0000
Subject: [PATCH] docs: keep the standalone session token in a Secret
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Option B: standalone" passed the Coder session token as a literal
--coder-session-token argument, so the token sat in plain text in the
Deployment spec. Store it in a Secret instead, expose it to the
container as CODER_SESSION_TOKEN with valueFrom.secretKeyRef, and pass
--coder-session-token=$(CODER_SESSION_TOKEN) so Kubernetes expands it
when the container starts. The Deployment then holds only a reference
to the Secret. No code change.

Part of #127.

_Generated with [`xum`](https://github.com/coder/xum) • Model: `anthropic:claude-opus-5-5` • Thinking: `xhigh`_

Change-Id: Ie11d1fdc4501b6d7843bddc3648e2057bfd68142
Signed-off-by: Thomas Kosiewski <tk@coder.com>
---
 docs/how-to/deploy-aggregated-apiserver.md | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/how-to/deploy-aggregated-apiserver.md b/docs/how-to/deploy-aggregated-apiserver.md
index ea069c73..03e4a80d 100644
--- a/docs/how-to/deploy-aggregated-apiserver.md
+++ b/docs/how-to/deploy-aggregated-apiserver.md
@@ -26,23 +26,35 @@ kubectl apply -f deploy/deployment.yaml
 
 Run only the aggregated API server (`--app=aggregated-apiserver`) and point it at a Coder instance yourself.
 
-Deploy, then set the backend:
+Save the Coder session token in a file, for example `./coder-session-token`. Store it in a Secret, deploy, then set the backend:
 
 ```bash
+kubectl -n coder-system create secret generic coder-k8s-session-token \
+  --from-file=token=./coder-session-token
+
 kubectl apply -f deploy/deployment.yaml
 
 kubectl -n coder-system patch deployment coder-k8s --type=json -p '[{
+  "op": "add",
+  "path": "/spec/template/spec/containers/0/env",
+  "value": [{
+    "name": "CODER_SESSION_TOKEN",
+    "valueFrom": {"secretKeyRef": {"name": "coder-k8s-session-token", "key": "token"}}
+  }]
+}, {
   "op": "add",
   "path": "/spec/template/spec/containers/0/args",
   "value": [
     "--app=aggregated-apiserver",
     "--coder-url=https://coder.example.com",
-    "--coder-session-token=replace-me",
+    "--coder-session-token=$(CODER_SESSION_TOKEN)",
     "--coder-namespace=coder-system"
   ]
 }]'
 ```
 
+Kubernetes replaces `$(CODER_SESSION_TOKEN)` with the value from the Secret when it starts the container, so the Deployment holds only a reference to the Secret, not the token. Keep the single quotes so that your shell does not expand it.
+
 Standalone mode serves health checks over HTTPS on port `6443`. Update the probes:
 
 ```bash