This documentation is for an older version (1.4.7) of Dagster. You can view the version of this page from our latest release below.
This guide is applicable to Dagster Cloud.
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 Cloud:
Dagster Cloud UI | Agent configuration | |
---|---|---|
Deployment type support | Serverless, Hybrid | Hybrid |
How it works | Environment variables are managed in the Dagster Cloud 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 Cloud, while those set at the deployment level bypass Dagster Cloud entirely. Refer to the Setting environment variables for Dagster Cloud 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. |
This section is applicable only if using the Dagster Cloud UI to manage environment variables.
To securely store environment variables defined using the Dagster Cloud UI, Dagster Cloud 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 Cloud:
In Dagster Cloud, 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.
This section is applicable only if using the Dagster Cloud UI to manage environment variables.
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 Cloud, 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.
This section is applicable only if using the Dagster Cloud UI to manage environment variables.
Built-in (system) Dagster Cloud environment variables are reserved and therefore unavailable for use. An error will surface in Dagster Cloud if a built-in variable name is used.
The simplest way to manage environment variables is to use Dagster Cloud's built-in manager which allows you to create and manage environment variables right in the UI.
To manage environment variables using the Dagster Cloud UI, you need:
Sign in to your Dagster Cloud 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 Cloud 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.
Only supported for Hybrid deployments.
For Dagster Cloud 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 Cloud 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 Cloud 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.
The following variables are available in every deployment of your Dagster Cloud instance, including full (e.g., prod
) and branch deployments.
Property | Description |
---|---|
DAGSTER_CLOUD_DEPLOYMENT_NAME | The name of the Dagster Cloud deployment. For example, prod . |
DAGSTER_CLOUD_IS_BRANCH_DEPLOYMENT | If 1 , the deployment is a branch deployment. Refer to the Branch Deployment variables section for a list of variables available in branch deployments. |
The following environment variables are currently available only in a branch deployment.
For every commit made to a branch, the following metadata is available:
Property | Description |
---|---|
DAGSTER_CLOUD_GIT_SHA | The SHA of the commit. |
DAGSTER_CLOUD_GIT_TIMESTAMP | The time the commit occurred. |
DAGSTER_CLOUD_GIT_AUTHOR_EMAIL | The email of the git user who authored the commit. |
DAGSTER_CLOUD_GIT_AUTHOR_NAME | The name of the git user who authored the commit. |
DAGSTER_CLOUD_GIT_MESSAGE | The message associated with the commit. |
DAGSTER_CLOUD_GIT_BRANCH | The name of the branch associated with the commit. |
DAGSTER_CLOUD_GIT_REPO | The name of the repository associated with the commit. |
DAGSTER_CLOUD_PULL_REQUEST_ID | The ID of the pull request associated with the commit. |
DAGSTER_CLOUD_PULL_REQUEST_STATUS | The status of the pull request at the time of the commit. Possible values are OPEN , CLOSED , and MERGED . |
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. |