Environment variables

A variable is a name and a value that a web service reads from its environment at runtime. Kuppit stores them encrypted, snapshots them into every deployment, and resolves the ones that point at other resources when the deployment is prepared.

Where variables live

Variables are set in two places:

• On a web service, on its Variables tab. These belong to that service alone.
• On an environment, on the environment's Variables tab. Every web service in the environment inherits them, and they appear on each service's Variables tab under Inherited from the environment.

A variable set on a service takes precedence over an inherited one of the same name.

Variables belong to environments, not projects. Production and staging each have their own set, and creating an environment from another lets you choose which values, and which secrets, to copy across.

Literals and references

A variable's value is one of two things.

A literal is text you typed: a feature flag, an API base URL, a log level.

A reference points at a variable another resource exposes. It is written with the resource's name and the variable's name:

DATABASE_URL = ${{ database.DATABASE_URL }}

Read it as: this service references a variable exposed by database. The value is not stored on the service. Kuppit composes it when it prepares a deployment, from the referenced resource's current state, so a service is always connected to the database as it is now.

What a resource exposes depends on its kind:

A reference can only target a resource in the same environment.

Secrets

Marking a variable as a secret makes it write-only. The value is encrypted, never returned by the dashboard, and shown only as its name. To change one, enter a complete replacement value; saving permanently overwrites the previous one for future deployments.

For references, secrecy follows the variable being referenced, not the name you gave it. A variable that resolves to PGPASSWORD or DATABASE_URL is a secret whatever it is called.

When a change takes effect

Every deployment carries a snapshot of the variables it was prepared with, and a running revision never changes underneath you. Editing a variable therefore does nothing to the current deployment. The service shows Runtime configuration has changed; choose Redeploy now to build the current commit again with the new values, or wait for the next push.

Rolling back to a previous deployment restores the variables it was deployed with, not the ones set now.

Names and limits

• Names match [A-Za-z_][A-Za-z0-9_]* and are at most 128 characters.
• Values are limited to 32 KiB each.
• PORT, K_SERVICE, K_REVISION and K_CONFIGURATION are set by the runtime and cannot be defined. PORT is the port your service must listen on; see Web services.

When a reference cannot be resolved

A reference is checked when a deployment is prepared. If it cannot be resolved, the deployment fails before anything is built and the deployment page says why:

Each of these is a configuration fault: fix the variable, then deploy again. The service's current deployment keeps serving throughout.