Set environment variables
Give an app plain variables and secrets by reference, and roll the change out with or without a redeploy.
A variable is either a plain value or a reference to a secret from Secrets. A secret's value is decrypted at deployment and handed to the machine, never stored on the app. An app holds up to 1000 variables, each value at most 8192 characters. Replace app-id with the app's id and secret-id with a secret's id.
Prerequisites
- Permission for
deploy:ManageEnvon the app. To bind a secret,secrets:GetSecretValueon it; binding grants it to thedeployconsumer. To redeploy in the same step,deploy:DeployApp. - In the console, also
deploy:DescribeAppto open the app's page (without it the page is not found).
Set the variables
- Open the app's Environment tab.
- Choose Add variable.
- In the new row, enter the variable name.
- Choose Value and enter the value, or choose Secret and, under Choose a secret…, choose the secret.
- Choose Save environment, or Save & redeploy (shown only with
deploy:DeployApp) to roll the change out at once.
dcloud deploy env replace app-id \
--vars '{"key":"LOG_LEVEL","valueKind":"plain","plainValue":"info"}' \
--vars '{"key":"API_TOKEN","valueKind":"secret","kmsSecretId":"secret-id"}' \
--redeployPUT /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/env
{
"vars": [
{ "key": "LOG_LEVEL", "valueKind": "plain", "plainValue": "info" },
{ "key": "API_TOKEN", "valueKind": "secret", "kmsSecretId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a" }
],
"redeploy": true
}The call replaces the whole environment.
resource "dcloud_app_env" "web" {
app_id = dcloud_app.web.id
vars = {
LOG_LEVEL = "info"
}
secret_vars = {
API_TOKEN = dcloud_secret.api_token.id
}
redeploy = true
}The resource owns every variable: a variable set elsewhere is removed on the next apply, and destroying it empties the environment.
Saving does not restart the app
The running container keeps the environment it started with. Save & redeploy, or
"redeploy": true on any environment write, rolls the change out; without it, the panel shows
Saved, not running. and what changed until someone redeploys. Choose Redeploy now on that
banner, or:
dcloud deploy redeploy apply app-id --reason "New LOG_LEVEL"The banner, and status in GET /deploy/api/apps/app-id/env, report the app as behind
when the environment was saved after the live deployment started, or a bound secret (a database
binding's included) changed since, including one synced from 1Password. An app with no live
deployment is never reported as behind.
A redeploy (from an environment change, an import, a database binding, a credential rotation or
Redeploy now) creates a deployment that runs exactly what the live deployment runs: the
same image, or the same pinned compose file. Nothing is rebuilt: an app built from a repository
reuses the live image by its digest, and is rebuilt from the same commit only when that image is no
longer in its registry repository (the deployment's activity says which). A configuration change is
never also a code change. An app with no live deployment yet has nothing to reuse: its redeploy
builds or pulls the current source. A redeploy needs deploy:DeployApp as well as the write itself.
What the containers receive
The machine hands the variables to the container in a file, so a long list costs nothing at start.
A plain value cannot contain a line break: it is refused with 400 "A value cannot contain a line
break, so bind a secret for multi-line material". A secret's value with line breaks (a PEM key, a
service-account JSON) reaches the container intact as an ordinary environment variable, so bring
such a value in as a secret (op://…, or a secret created in Secrets). For a compose app, which services receive which variables is in
Compose files.
Scheduled jobs get the environment as of the live deployment: a variable saved without redeploying reaches jobs when it reaches the app.
Result
After the redeploy, the app's containers start with the new environment. The Environment tab also lists Secrets this app uses: where each value comes from, and the version the app last read.