Skip to content

docs(concepts): clarify override env is literal-only, secrets via template #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DrummyFloyd merged 1 commit into from
Jul 24, 2026
Merged

docs(concepts): clarify override env is literal-only, secrets via template #13

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion docs/concepts/templates-and-protocols.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,9 @@ order:
it server-side when a session starts — the browser never sees the
values. Ship it with External Secrets/Vault; typically the same
Secret also feeds the pod via env `valueFrom` (e.g.
`WAAS_DESKTOP_PASSWORD`) so both sides agree.
`WAAS_DESKTOP_PASSWORD`) so both sides agree. Env `valueFrom` is a
**template-side** channel — workspace overrides only ever carry
literal values (see [Creator overrides](#creator-overrides)).
2. **Generated per-workspace credentials** — the default when nothing
explicit is provided: the operator generates a random credential per
workspace, stores it in a Secret next to the CR, wires it into the
Expand Down Expand Up @@ -158,6 +160,21 @@ the effective allow-list is the **intersection** of both. Enforcement
is server-side (admission webhook + a reconciler re-check), and every
applied override is audited (field and env var _names_, never values).

:::note Overrides carry literal values, not Secret references
An override `env` entry may set only a **literal `value`**. `valueFrom`
sources — `secretKeyRef`, `configMapKeyRef`, `fieldRef`,
`resourceFieldRef` — are **rejected** in a workspace override (by the
same admission webhook that enforces the allow-list, and stripped again
by the operator when the workload is rendered). Wiring a Secret into a
desktop is a **template** decision: the admin who authors the template
references it through env `valueFrom` or
[`credentialsSecretRef`](#credentials), both resolved against the
workspace's own namespace. The template — authored by an admin,
typically through GitOps — is therefore the only channel that can point
a desktop at a cluster Secret; a workspace creator tunes values, never
references Secrets.
:::

:::warning
Allow-listing `volumes` lets users mount arbitrary volume sources —
including `hostPath`. Only enable it on templates aimed at trusted
Expand Down