Dagster+ environment variables and secrets#

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.

Understanding environment variables and secrets#

• Overview
• Storage and encryption
• Scope
• Reserved variables

Overview#

There are two ways to declare and manage variables in Dagster+:

Storage and encryption#

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.

Scope#

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.

Same variable, different scopes and values#

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.

Reserved variables#

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.

Managing environment variables#

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.

Using the Dagster+ UI#

• Creating new variables
• Editing, viewing, and deleting variables
• Exporting variables to a .env file

Creating new variables#

1. Sign in to your Dagster+ account.

2. Click Deployment > Environment variables.

3. Click + Add Environment Variable to add a new environment variable.

4. In the window that displays, fill in the following:

   • Name - Enter a name for the environment variable. This is how the variable will be referenced in your code.
   • Value - Enter a value for the environment variable.
   • In Deployment Scope, select the deployment(s) where the variable should be accessible:
     • Full deployment - The variable will be available to selected code locations in the full deployment
     • Branch deployments - The variable will be available to selected code locations in Branch Deployments
     • Local - If selected, the variable will be included when exporting environment variables to a local .env file
   • In Code Location Scope, select the code location(s) where the variable should be accessible. At least one code location is required. Refer to the Scope section for more info.

   For example:

   

5. When finished, click Save. Dagster+ will automatically re-deploy the workspace to apply the changes.

Editing, viewing, and deleting variables#

After the environment variable is created:

• To edit an environment variable, click the Edit button.
• To view an environment variable's value, click the eye icon in the variable's Value column. Click the icon again to conceal the value.
• To delete an environment variable, click the Trash icon and confirm the deletion when prompted.

Exporting variables to a .env file#

All variables with the local deployment scope can be exported to an .env file and used locally. To create the file:

1. In the Environment variables tab, click the menu next to + Add environment variable:

   

2. Click Download local environment variables

3. 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.

Using agent configuration (Hybrid)#

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.

Accessing environment variables in Dagster code#

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.

Reserved environment variables#

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.

Troubleshooting#

Related#