Environments

Maintain separate execution environments with different configurations for your tasks, runbooks, and more.

Environments is now available in beta. Information below is subject to change.

Overview

The environments feature allows your team to maintain separate execution environments with their own tasks, runbooks, schedules, resources, and config variables. Environments are isolated from one another, meaning a task in a certain environment will only have access to the resources and config variables in that environment.

Depending on the execution environment, the List Users task will resolve different resource
configurations.
Depending on the execution environment, the List Users task will resolve different resource configurations.

Environments are powerful for the following use cases (and more):

  • Test changes in a dev or staging environment before releasing to your team
  • Run the same task against different configs, resources and agents
  • Create a safe isolated playground to experiment with new tasks and/or runbooks

Manage environments

Get started by creating your first environment via the settings page. Here, you can create, modify and archive your existing environments. All teams already have a single, default "Production" environment.

When you create an environment, you will have the opportunity to choose a name, slug, and template from which to create the environment. The slug identifies which environment to use when working with the CLI (e.g. listing tasks, deploying tasks, and updating configs/resources).

To clone your existing tasks, runbooks, configs, resources and schedules when creating a new environment, select your existing Production environment as the template. Schedules in newly created environments will be disabled by default.

Promotion

Tasks, runbooks, configs, resources and schedules can be promoted via the UI, CLI and the deployments feature. Promoting allows you to to initialize and/or sync an entity across environments. For example, the same task definition that depends on a set of configs and/or resources can be deployed to multiple environments. When the task is run in a specific environment, it will run with the config/resource values specified in that environment.

Promoting tasks via the CLI

You can promote tasks via the CLI by appending --env <env_slug> to your deploy command:

bash
Copied
1
airplane deploy ./slug.task.yaml --env your_env_slug

A recommended approach is to deploy your task to your development environment, test that it works properly and then deploy it to your production environment.

Promoting tasks via the UI

You can promote tasks via the UI by selecting promote in the dropdown menu for the task. You can select the environment you would like to promote to via the dropdown in the modal that pops up.

Promoting tasks via Deployments

You can specify different git repo and branch configurations per environment. To do so, navigate to the settings page and change the active environment in the environment dropdown. The configuration you see reflects the configuration in the currently selected environment.

To configure different settings, navigate to the settings page and change the environment via the environment dropdown. The configuration you see reflects the configuration in the selected environment.

A recommended approach is to configure two separate branches for your development and production environments. Changes can be merged to your development branch and then merged into your production branch once they are verified.

Other entities

While the examples here only focus on tasks, they apply to all entities in the Airplane platform, including runbooks, configs, resources and schedules. Configs can be manipulated via the CLI using the same --env <env_slug> argument and can be promoted via the UI. Runbooks, schedules and resources can be promoted via the UI only (since you cannot manipulate them via the CLI).

Task execution

Certain environment-specific information is available via environment variables when your task runs, as well as via JST interpolation.

Environment variables:

  • AIRPLANE_ENV_ID: "env20220125z7pz51c"
  • AIRPLANE_ENV_SLUG: "prod"

JavaScript template evaluation variables:

  • env.id: "env20220125z7pz51c"
  • env.slug: "prod"
  • env.name: "Production"
  • env.default: true

For a full list of available variables for tasks and runbooks, see the JavaScript templates Globals reference.

JavaScript template interpolation can be used when setting run constraints. This makes it possible to ensure tasks in certain environments run only on certain agents:

Example walkthrough

Let's say you're working on a new task that you want to develop in your dev environment and then promote to prod once it's working correctly.

  • Create a dev environment in the app settings page
  • Create a SQL task named Environments Demo that will run against the demo db with the following query:
sql
Copied
1
SELECT company_name, total_dollars
2
FROM accounts
3
ORDER BY total_dollars DESC
  • Execute the task in your dev environment and ensure the task runs properly
  • Initialize your task in code via the Airplane CLI:
bash
Copied
1
airplane init --from environments_demo --env dev
  • Make an edit to environments_demo.sql to add a column (country) to the select clause:
sql
Copied
1
SELECT company_name, total_dollars, country
2
FROM accounts
3
ORDER BY total_dollars DESC
  • Deploy the task to your dev environment:
bash
Copied
1
airplane deploy environments_demo.task.yaml --env dev
  • Execute the task again in your dev environment and ensure the task runs properly
  • Promote the task to production by deploying to prod:
bash
Copied
1
airplane deploy environments_demo.task.yaml --env prod
  • Switch to your production environment and run the task
  • Alternatively, you can promote the task from dev to prod by opening the task in dev and promoting the task via the UI.