Set variables and references

Variables reach a service's processes as environment variables. Each variable lives on one tier, and the most specific tier wins: a service's own LOG_LEVEL beats the environment's, which beats the project's.

An external resource is the lowest tier: any other tier overrides it. A variable can be secret: its value is sealed, shown as dots, and revealed only on request.

Before you beginCopy Anchor Link

• You need the deployer role to add, change and reveal variables, and the admin role to add an external resource. A viewer sees keys with secrets masked.
• The environment tier and the service tier are staged as a change set and take effect when you deploy it. The project tier saves at once and applies the next time each service deploys.

Add a variable to a serviceCopy Anchor Link

To change a secret later, select its value and type the replacement. Leaving the field blank keeps the sealed value.

Share a variable with every service in an environmentCopy Anchor Link

1. Right-click an empty spot on the canvas and select Project variables. The panel names the environment.
2. Select + New shared variable, enter a key and value, and select Stage.
3. Deploy the staged change as above.

Every service in the environment inherits the variable unless it sets its own. A service's Variables tab shows an inherited row with a shared tag. Select its value to open the panel it comes from. Deploying the change redeploys every service that inherits the key, and every service that references one of them.

Share a variable with every environmentCopy Anchor Link

1. Right-click the canvas and select Project settings….
2. Under Project variables, select Add variable. Enter the Key and Value, tick Secret to seal it, and select Stage variable.
3. Select Save changes in the bar that appears above the list. Discard drops the staged change.

A project variable is saved immediately, outside any change set, and starts no deployment. Each service picks it up the next time it deploys. An environment or service value with the same key overrides it.

Point a value at another serviceCopy Anchor Link

A value can contain expressions between ${{ and }}. Type ${{ in any value field to get suggestions: the services of the environment, the keys each one has, and the functions below.

An expression can sit inside other text:

API_URL      = http://${{ host(api) }}:8080/v1
DATABASE_URL = ${{ db.DATABASE_URL }}
REDIS_URL    = redis://:${{ cache.REDIS_PASSWORD }}@${{ host(cache) }}:6379/0
JWT_SECRET   = ${{ secret(64) }}

In ${{ service.KEY }}, service is the service's slug as shown on the canvas, and KEY any key that service has on any tier it sees.

• Checked when you stage. A reference to a service that does not exist, or to a key that service will not have, is refused. The message lists the keys the service does have. For a project variable only the service is checked, because its keys differ per environment.
• Resolved at every deploy. A change to the referenced value redeploys the services that reference it.
• Secrets stay secret. A reference to a secret is resolved at deploy time. The resolved value goes to the cluster and is never stored on the release.
• Draws the canvas. Every reference is a dependency, and the canvas draws an edge for it. A reference also makes the service deploy after the one it names.

References are followed up to five deep. A cycle, or a reference whose target is gone, stops the deploy with a message that names the chain. ${{ inputs.KEY }} exists only in templates. Any other text between the braces is refused when you stage it. The full grammar is in Variable expressions.

Generate a secret valueCopy Anchor Link

Next to the value field of a key that names a secret your app makes up, such as SESSION_SECRET or ENCRYPTION_KEY, select Generate a random value. The field becomes ${{ secret(32) }}, and the variable is stored as a secret. Keys that name something another party issues, such as an API token, get no offer.

Staging the same key again draws a new value. Anything that still uses the old value stops working once you deploy, so the button reads Generate a new value on a variable that already has one.

Import variable names from an env fileCopy Anchor Link

1. On a Variables tab or the Project variables panel, select Import variables.
2. Choose From repository to read an example file such as .env.example from a service's repository, or Paste or upload to give the file's text.
3. Review the list. Each name is staged empty; the file's example values are shown as hints and never copied. Names that look like a secret your app makes up are offered a generated value: select Generate all or untick generate per row.
4. Select the button at the foot of the dialog, for example Stage 5 empty variables.

A variable that already has a value is kept unless you tick it. Replacing one asks "Replace KEY? It already has a value." and the button reads Replace and stage.

Reveal a secretCopy Anchor Link

Select Reveal on a secret's row. The value shows for 30 seconds, then hides again. Revealing is recorded as an audit event with the key and never the value. Hide closes it sooner.

Variables that a nebula.toml setsCopy Anchor Link

A variable that the service's nebula.toml names under [env], or that a project's nebula.toml writes, is read-only in the console and carries a badge naming the file and commit. Change it in the file and push, or remove the key from the file to edit it in the console.

Empty variablesCopy Anchor Link

An empty value is legal, and a deploy never waits for one. When a service has any, its Variables tab says so above the list and names every one: "5 variables are empty in Production: A, B, C, D, E. The service starts with them empty." Each such row carries an empty tag. An empty secret counts, without its value being opened.

Add an external resourceCopy Anchor Link

Use an external resource for a database, cache or SMTP server the cluster does not run.

1. Right-click the canvas, select Project variables, and under External resources select + Add external resource.
2. Enter a Name, choose the Kind (Postgres, MySQL, Redis, MongoDB, S3, SMTP or Other), add its variables, and under Link to services choose the services that need them.

The variables are sealed. Linked services receive them on their next deploy. A removed resource stops reaching them on their next deploy too.

VerifyCopy Anchor Link

After the deployment is healthy, the service runs with the new value. If a key is wrong or a reference does not resolve, the deployment fails with a message on the Deployments tab; see Deployments troubleshooting.

Next stepsCopy Anchor Link

• Create and connect a database: connection variables are references to the database's own.
• Release commands and files: mount a variable as a file.
• Variable expressions: where each expression is allowed.