Skip to main content
A secret is a value a function needs that must not live in its version, such as an API key. Secrets belong to a tenant. A version names the ones it needs, and the host fetches their values when it runs an invocation, so a value is never stored with the version or baked into its snapshot.

Where secrets are kept

The server keeps secrets through one provider, chosen by SECRET_PROVIDER: The external providers name every secret under SECRETS_PREFIX when it is set. With the default provider and no ENCRYPTION_KEY, the server starts with a warning and has no secrets: a spec that uses them is FAILED_PRECONDITION.

Naming secrets in a spec

spec.secrets maps an environment variable name to the name of a secret the same function’s secret_values created. Reuse the name from the function’s stored spec, which GetFunctionVersion returns:
Every secret a spec names must belong to the same function, so one function never reads another’s, or the version is refused with PERMISSION_DENIED. It must also exist when the version is created, or the version is refused with NOT_FOUND.

Creating secrets with a version

CreateFunction and CreateFunctionVersion take secret_values, a map of variable name to value. The server stores each value as a new secret and names it in the version’s spec.secrets for you. The name is the function id, a random suffix shared by that version’s values, and the variable, such as <function-id>.1a2b3c4d.CLEARBIT_KEY. Every version gets secrets of its own this way, so a new version never changes what an older one reads. A value must not be empty.
spec.env is not for secrets. Its values are part of the version and visible wherever the version is, in the API and the web UI.

How a value reaches the function

  1. A host takes an invocation of a version that names secrets.
  2. It asks a server for the values over the bus. The server answers only a host that has heartbeated recently, and only for the secrets that version names, in the version’s own tenant.
  3. The host keeps the values in memory, never on disk, for SECRETS_REFRESH_INTERVAL, 5 minutes by default, then asks again. A fetch that fails leaves the last value in use.
  4. The host sends the values to the supervisor with the invocation, and the supervisor adds them to the function process’s environment last, so they win over spec.env and the image’s Env.
When secret_values writes new secrets, the server tells every host to drop those names from its cache, so the next invocation reads the new value. The refresh interval is the backstop when that message is missed. A secret the host cannot get fails the attempt as a platform error, which retries like any other. Secrets are part of an artifact by name only. The values never reach a snapshot, since they are passed per invocation.