Skip to content

Secrets: how they are managed and mapped at runtime

A secret is a named value under a group, optionally narrowed to an environment and a zone. The console never shows a value back: not on the Secrets page, not in the API, not in backups, not in logs. Super admins and group admins add the values, read the names and delete them. A viewer cannot open the Secrets page at all.

The secrets page

Names, scopes and nothing else.

Scope

Scope Applies to
group only every environment and zone of the group
group + environment that environment in every zone
group + environment + zone that zone of that environment

The most specific scope wins on a name clash. On deploy the console resolves the secrets that match the target environment and zone.

Add one

Secrets → choose the group → name, value, optional environment and zone → Add secret. The page is open to super admins and group admins only.

curl -s -H "X-Ramen-Api-Key: $RMN" -H 'Content-Type: application/json' \
  -X POST https://<edge>/api/v1/groups/demo/secrets \
  -d '{"name":"OPENAI_API_KEY","value":"sk-...","env":"prod","zone":"a"}'

Then deploy the environment. Secrets reach workers only through a deploy.

How a secret reaches your code

The deploy writes each resolved secret into the zone's Secret as RAMEN_SECRET_<GROUP>__<NAME>, upper-cased. The runtime maps it two ways:

  • In call arguments. Any string a client passes that contains {{$demo.OPENAI_API_KEY}} is substituted before the function runs. Nested strings too. Unknown references stay literal.
  • Through mcp/env.yaml. The worker renders the file's {{$group.NAME}} references and exports every key to the runtime process at load. Code reads os.environ["DB_URL"].

Values are redacted from exception messages and never logged. A reference with no secret behind it is skipped with a warning so the rest of the file still applies.

Where values live

RAMEN_SECRETS_BACKEND Where What the worker identity needs
store the console store, Fernet-encrypted with RAMEN_FERNET_KEY (local, kind) nothing; the console injects the value on deploy
gcp Secret Manager ramen-<group>-<env or all>-<zone or all>-<NAME> secretAccessor on ramen-<group>-*, granted at zone creation
aws Secrets Manager ramen/<group>/<env or all>/<zone or all>/<NAME> GetSecretValue on ramen/<group>/*, granted at zone creation
azure Key Vault ramen--<group>--<env or all>--<zone or all>--<NAME> (characters Key Vault refuses, - and _ included, escaped as -XX hex) Key Vault Secrets User on exactly the group's secrets, granted at zone creation

The charts set gcp, aws and azure. MCP keys are stored through the same backend.

The console's own secrets (1.0.0)

The console keeps secrets of its own: the SMTP password, the GitHub App private key, identity-provider client secrets, telemetry headers, group repo tokens and throttle Redis URLs. On a cloud each of them is written to the same secret manager as a secret of its own (ramenc-… on GCP, ramenc--… on Azure, ramen-console/… on AWS) and the store keeps only a reference; a new value is a new secret and the old one is deleted. No worker identity can read them: the names fall outside every worker's grant. Locally (store) they stay Fernet-encrypted in the store. Values written before 1.0.0 are moved on the first start. Password and key hashes are not secrets in this sense and stay in the store. The Config page lists each section's settings and shows a secret only as set (hidden) or not set; every secret the console reads or writes is scrubbed from its logs, deploy logs and backups (a URL's user:pass@ too).

Special names

GITHUB_TOKEN is used by the console to clone a private group repo. It can be group- or environment-scoped. The group's fallback GitHub token field on the group page is the alternative.

Rotate

Delete and add under the same name, then deploy. Workers pick the new value up during the canary reload. The rotate-keys skill covers keys and the Fernet key.