Where secrets are kept
The server keeps secrets through one provider, chosen bySECRET_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.
How a value reaches the function
- A host takes an invocation of a version that names secrets.
- 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.
- 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. - 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.envand the image’sEnv.
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.