Environment variables
Literals, references, generated values, secrets and shared groups.
Each variable is one of:
| Form | Meaning |
|---|---|
KEY: text | A literal. Numbers and booleans become strings. |
KEY: ${db.url} | A reference. It can sit inside text: "${cache.url}/1". $$ is a literal $. |
KEY: { generate: secret } | A random value made once per sandbox and kept for its life. secret is 48 URL-safe characters, hex32 is 32 random bytes as 64 hex characters, base64_32 is 32 random bytes as 44 base64 characters, uuid is a UUID. |
KEY: { generate: secret, length: 32 } | Exactly that many characters (16 to 256): letters and digits for secret, lowercase hex for hex. Use it when the app wants a key of a given length, such as a 32-character encryption key. |
KEY: { secret: <ref> } | A value from the project's secret store, in staging and production. Sandboxes never get staging or production values: it is empty there and parity check warns. Use generate: for values a sandbox needs. |
KEY: { unset: true } | Remove a variable a group or the platform set. |
References. ${<name>.<attr>} for a managed entry or a service, or the long forms ${managed.db.url} and ${service.web.url}. Services have url (http://<service>:<port>, inside the sandbox) and public_url, the URL of the first entry in expose; public_url.<host> is another exposed host's, as in ${web.public_url.link}. Services reach public URLs too, so a server-side call to ${web.public_url} (an OAuth callback, a webhook to itself) reaches the service. ${sandbox.id} and ${sandbox.domain} are also available: a public host is <host>--${sandbox.domain}. ${env_groups.<group>.<KEY>} is a group's variable, generated values included, so one secret can have the name each image expects: SPICEDB_GRPC_PRESHARED_KEY: ${env_groups.shared.AUTHZED_TOKEN}. Kubernetes' $(VAR) form is refused, because it would reach the app as literal text. KEY: db.url without ${} is refused, since it's almost always a forgotten ${}. Inside a one-line { ... }, quote references: env: { A: "${db.url}" }.
Groups. env_groups.<name> is a map of variables in the same forms. env_from: [<name>] gives them to a service. A value generated in a group is the same in every service that includes it, which is how services share a secret.
Precedence. Standard variables from depends_on first, then env_from groups, then the service's own env. Two groups setting the same key is an error.
Reuse. YAML anchors and aliases work anywhere, and <<: *common merges a mapping into another, as in Compose:
x-deps: &deps [db, cache]
services:
web: { build: ., depends_on: *deps }
worker: { build: { from: web }, command: npm run worker, depends_on: *deps }