Environment variables, which are key-value pairs configured outside your source code, allow you to dynamically modify application behavior depending on environment.
Using environment variables, you can define various configuration options for your Dagster application and securely set up secrets. For example, instead of hard-coding database credentials - which is bad practice and cumbersome for development - you can use environment variables to supply user details. This allows you to parameterize your pipeline without modifying code or insecurely storing sensitive data.
There are two ways to declare and manage variables in Dagster+:
Dagster+ UI | Agent configuration | |
---|---|---|
Deployment type support | Serverless, Hybrid | Hybrid |
How it works | Environment variables are managed in the Dagster+ UI. Values are pulled from storage and decrypted when your code is executed. | Environment variables are defined in the agent's configuration. Variables set at the code location level will pass through Dagster+, while those set at the deployment level bypass Dagster+ entirely. Refer to the Setting environment variables for Dagster+ agents guide for more info. |
Requirements |
| Ability to modify your dagster.yaml and dagster_cloud.yaml files |
Limitations |
| Variable names:
|
Storage and encryption | Uses Amazon Key Management Services (KMS) and envelope encryption. Refer to the Storage and encryption section for more info. | Dependent on agent type (ex: Kubernetes) |
Scope | Scoped by deployment (full and branch) and optionally, code location | Scoped by code location. Variables can be set for a full deployment (all code locations) or on a per-code location basis. |
To securely store environment variables defined using the Dagster+ UI, Dagster+ uses Amazon Key Management Services (KMS) and envelope encryption. Envelope encryption is a multi-layered approach to key encryption. Plaintext data is encrypted using a data key, and then the data under the data key is encrypted under another key.
Here's a look at how it works in Dagster+:
In Dagster+, each customer account is assigned a unique key, which then encrypts the data associated with that account. All customer keys are encrypted using a non-exportable AWS KMS master key.
This approach isolates each account's data and reduces the risk of exposure by limiting the amount of data a single key can access.
Environment variables can be scoped to specific deployments and/or code locations. When creating or modifying an environment variable, you'll be prompted to select the deployment(s) to scope the variable to:
Full deployment - Variables with this scope will be available to selected code locations in the full deployment
Branch deployments - Variables with this scope will be available to selected code locations in Branch Deployments.
Note: While viewing a Branch Deployment in Dagster+, variables will be read-only. Environment variables must be managed in the Branch Deployment's parent full deployment, which will usually be prod
.
Local - Variables with this scope will be included when downloading variables to a local .env
file
By default, new environment variables default to all deployments and all code locations.
You can create multiple instances of the same environment variable with different values for different scopes. Each instance of the variable can then be scoped to a deployment and code location (or locations). This approach can be useful for parameterizing behavior by environment without needing to modify your application code.
For example, let's say we want to use different database passwords in production and testing (Branch Deployments). In our code, we use the SNOWFLAKE_PASSWORD
environment variable to pass in the database password. To use different passwords between production and Branch Deployments, we can create two instances of SNOWFLAKE_PASSWORD
. One instance is scoped to the prod
deployment and the other only to Branch Deployments:
In this example, the value of SNOWFLAKE_PASSWORD
would be production_password
in the prod
deployment and testing_password
in a Branch Deployment.
Built-in (system) Dagster+ environment variables are reserved and therefore unavailable for use. An error will surface in Dagster+ if a built-in variable name is used.
The simplest way to manage environment variables is to use Dagster+'s built-in manager which allows you to create and manage environment variables right in the UI.
Sign in to your Dagster+ account.
Click Deployment > Environment variables.
Click + Add Environment Variable to add a new environment variable.
In the window that displays, fill in the following:
.env
fileFor example:
When finished, click Save. Dagster+ will automatically re-deploy the workspace to apply the changes.
After the environment variable is created:
All variables with the local
deployment scope can be exported to an .env
file and used locally. To create the file:
In the Environment variables tab, click the menu next to + Add environment variable:
Click Download local environment variables
Save the file. Note: If saved to the same folder where you run dagster-webserver
, Dagster will automatically load the variables in the .env
file when the webserver is started.
For Dagster+ Hybrid deployments, making environment variables accessible is accomplished by adding them to your agent's configuration. How this is accomplished depends on the agent type.
Refer to the Setting environment variables for Dagster+ agents guide for more info.
Ready to start using environment variables in your Dagster code? Refer to the Using environment variables and secrets in Dagster code guide for more info and examples.
Dagster+ provides a set of built-in, automatically populated environment variables, such as the name of a deployment or details about a branch deployment commit, that can be used to modify behavior based on environment. Refer to the Reserved Dagster+ environment variables reference for more information.
Error | Description and resolution |
---|---|
[variable] is a reserved environment variable name. | Dagster reserves the names of built-in (system) variables. To resolve, change the variable's name to a name that isn't currently reserved and meets the other naming requirements. |
Environment variables must be no greater than 4KB in size. | To resolve, reduce the size of the environment variable's value to less than the maximum of 4KB. |
Environment variable names must be no longer than 512 characters. | To resolve, reduce the number of characters in the variable's name. |
Invalid environment variable name [variable] | The name of the environment variable doesn't meet one or several of Dagster's naming requirements. To resolve, change the variable's name to:
|
Deployment [deployment_name] has reached the maximum of 1,000 environment variables. | The maximum number of environment variables for the full deployment has been reached. New variables cannot be added. Remove any unneeded variables to reduce the total below the maximum, then add new variables. |