#12434: Add K8s support with SA Trust architecture

#### Summary Adds a Kubernetes Service Account Trust authentication method that enables workers to authenticate with the gateway using their pod SA token. This allows zero-touch scaling of worker nodes in Kubernetes — new pods authenticate automatically via the K8s TokenReview API, bypassing interactive device pairing. #### Use Cases - **Production K8s deployments**: Run gateway and workers as separate pods with independent scaling. - **Autoscaling**: HPA or manual `kubectl scale` spawns workers that authenticate instantly. - **Multi-tenant isolation**: Deploy multiple isolated OpenClaw instances via Helm releases in separate namespaces. #### Behavior Changes - New auth method `k8s-sa-trust` added to gateway authentication. - Workers with `--k8s-trust` flag read their pod SA token and present it on connect. - Gateway validates tokens via K8s TokenReview API when `auth.k8sTrust` is configured. - Workers authenticated via SA Trust skip device pairing (`skipPairing`). - No changes to existing auth flows — SA Trust is entirely opt-in. #### Existing Functionality Check - [x] Searched codebase for existing K8s/container auth — none found. - [x] Searched GitHub issues for Kubernetes deployment requests. - [x] Reviewed `docs/install/docker.md` — Docker guide exists but no K8s equivalent. #### Changes **Source code** (10 files): | File | Change | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `src/gateway/k8s-auth.ts` | New `K8sAuthenticator` class — validates SA tokens via TokenReview API, namespace/SA allowlisting | | `src/gateway/k8s-auth.test.ts` | 13 unit tests covering validation, allowlisting, error handling, singleton | | `src/config/types.gateway.ts` | `k8sTrust` type definition on `GatewayAuthConfig` | | `src/config/zod-schema.ts` | Zod schema for `k8sTrust` config validation | | `src/gateway/auth.ts` | `"k8s-sa-trust"` added to auth method union type | | `src/gateway/protocol/schema/frames.ts` | `k8sToken` field in `ConnectParams` | | `src/gateway/client.ts` | `k8sServiceAccountToken` option in auth payload | | `src/gateway/server/ws-connection/message-handler.ts` | SA Trust validation + `skipPairing` for `k8s-sa-trust` | | `src/node-host/runner.ts` | `k8sTrust` option, reads SA token from pod volume mount | | `src/cli/node-cli/register.ts` | `--k8s-trust` CLI flag | **Deployment files** (22 files): | Path | Contents | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deploy/k8s/` | Raw manifests: namespace, rbac, gateway-config, gateway, worker, networkpolicy, README | | `deploy/helm/openclaw/` | Full Helm chart: Chart.yaml, values.yaml, values-local.yaml, 12 templates (statefulset, deployment, HPA, RBAC, configmap, secret, service, ingress, networkpolicy, service accounts, helpers, NOTES) | **Documentation** (1 file + Mintlify nav): | Path | Contents | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `docs/gateway/kubernetes.md` | Architecture doc with Mintlify frontmatter: SA Trust design, threat model, token flow, failure modes, scaling behavior | | `docs/docs.json` | Added `gateway/kubernetes` to navigation + `/kubernetes` and `/k8s` redirects | #### Tests - 13 unit tests in `src/gateway/k8s-auth.test.ts` — all passing. - Tests cover: token validation (valid, invalid, expired), namespace allowlisting, service account allowlisting, combined restrictions, error handling (API errors, network failures, malformed responses), singleton pattern. - `pnpm test` — full suite passes. #### Manual Testing ### Prerequisites - K3s (or any K8s cluster) with `kubectl` access. - Container image built and available to the cluster. ### Steps 1. Deploy gateway with SA Trust config enabled. 2. Deploy worker pods with `--k8s-trust` flag. 3. Verify workers authenticate via SA Trust in gateway logs. 4. Scale workers: `kubectl scale deployment openclaw-worker --replicas=5`. 5. Verify new pods authenticate automatically (~10 seconds). #### Evidence - **K3s cluster**: v1.34.3+k3s1, single-node, 3 namespaces deployed simultaneously. - **Dynamic scaling**: 2 → 5 workers, all authenticated via SA Trust. - **Helm deployments**: `oc-test-1` and `oc-test-2` namespaces via `helm install`, both operational. - **Unit tests**: 13/13 passing. **Sign-Off** - Models used: Claude Opus 4 - Submitter effort: multi-session (architecture design, implementation, deployment testing, Helm chart, debugging 6 deployment issues) **AI Disclosure** This PR was prepared with assistance from Claude Opus 4. The architecture design, implementation, K8s deployment testing, Helm chart creation, and debugging were developed collaboratively. I understand the code and the changes. Tested via automated tests (855/856 pass) and manual K3s deployment (3 namespaces, dynamic scaling 2→5 workers). lobster-biscuit --- #### Pre-PR Checklist - [x] `pnpm build` — passes - [x] `pnpm test` — 855/856 pass (1 pre-existing EACCES failure unrelated to this PR) - [x] `pnpm check` — passes (tsgo + lint + format) - [x] Relocate files from `.nozim/` to final locations - [x] Add Mintlify frontmatter to docs - [x] Update `docs/docs.json` navigation + redirects - [x] Add changelog entry - [x] Rebase onto latest `main` <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR adds an opt-in Kubernetes ServiceAccount Trust auth path for gateway↔worker connections. Workers can send their projected pod ServiceAccount JWT (`k8sToken`) during the connect handshake, and the gateway validates it via the Kubernetes TokenReview API when `gateway.auth.k8sTrust` is enabled. On successful validation/allowlisting, the connection is marked as `k8s-sa-trust` and device pairing is skipped. The PR also adds supporting CLI/runtime flags for node-host, config/zod schema updates, and Kubernetes deployment artifacts (raw manifests + Helm chart) plus documentation updates. <h3>Confidence Score: 3/5</h3> - This PR is mergeable after addressing a couple of concrete security/operational issues in the new K8s TokenReview authentication path. - Core flow (worker sends SA token, gateway calls TokenReview, allowlists identity) is reasonable and well-tested, but the gateway’s TokenReview client currently ignores the configured CA cert (making in-cluster TLS likely to fail without extra env), and the allowlist defaults to allow-all when enabled, which is an unsafe default for an authentication feature that also bypasses device pairing. - src/gateway/k8s-auth.ts; src/gateway/server/ws-connection/message-handler.ts <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->