Skip to main content
This feature is in Public Preview.
A bundle is a unit of code that you deploy to a Deployment. Astro supports two kinds:
  • Dag bundles carry Dag files. Each Dag bundle has a name, its own version history, and its own deploys.
  • Non-Dag bundles carry supporting code, such as a dbt project. Each non-Dag bundle is identified by the path it’s mounted at, and is served alongside one or more Dag bundles.
Every Deployment with Dag-only deploys enabled has a Dag bundle named main. It’s the default target for astro deploy --dags, and you can’t delete it. On Airflow 3 Deployments, you can create more named Dag bundles and deploy to each one separately. Multiple Dag bundles are useful when several teams or repositories share a Deployment. Each team deploys its own bundle without carrying the other teams’ code, and a change to one bundle doesn’t redeploy the rest.
Airflow 3Creating Dag bundles other than main requires an Airflow 3.x Deployment. Airflow 2 Deployments keep the single main bundle.

​
Prerequisites

  • An Astro Deployment running Airflow 3 with Dag-only deploys enabled.
  • The Astro CLI version 1.46 or later.
  • Workspace Author permissions or higher to create, update, and delete bundles. Workspace Member permissions are enough to view them.
Bundles aren’t available on Deployments that use Remote Execution. Those Deployments configure Dag bundles through the Remote Execution Agent instead. See Configure Dag sources.

​
How bundles relate to each other

A Deployment has one or more Dag bundles and any number of non-Dag bundles, up to a combined limit. Each non-Dag bundle is associated with at least one Dag bundle, which determines the Airflow workers that download it. For example, a Deployment shared by a finance team and a machine learning team might have three Dag bundles, main, finance, and ml, alongside a dbt project mounted at /usr/local/airflow/dbt/revenue and shared helper code mounted at /usr/local/airflow/include/shared. The finance team deploys to finance on its own schedule, and the machine learning team deploys to ml on its own schedule. Neither deploy affects the other. The dbt project is served alongside finance only, and the shared helper code is served alongside both.

​
Create a Dag bundle

Astro creates the main bundle automatically when you enable Dag-only deploys. For every other Dag bundle, you must create it before you can deploy to it — Astro doesn’t create them automatically. Bundle names must be 1-32 characters and can contain only lowercase letters, numbers, dashes, and underscores. The name main is reserved.
  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Bundles, then click Dag.
  3. Click New Dag bundle.
  4. Enter a Name, optionally add a Description, then click Create bundle.
A new Dag bundle has no version until you deploy to it. Until then, it’s registered on the Deployment but isn’t served to Airflow.

​
Deploy Dags to a named bundle

Use the --dag-bundle-name flag to target a bundle:
The bundle must already exist. If it doesn’t, the deploy fails and the Astro CLI tells you to create it first. Without --dag-bundle-name, a Dag deploy targets main, so existing commands and CI/CD pipelines keep working unchanged:
Each bundle replaces its own contents on deploy. Deploying to finance replaces the Dags in finance and leaves every other bundle alone.
You can’t use --dag-bundle-name with --image. Named bundles apply only to deploys that include Dags.

​
Deploy a non-Dag bundle

A non-Dag bundle is created the first time you deploy to a mount path that the Deployment hasn’t seen before. To deploy one and choose where it mounts:
  • --non-dags-mount-path is required. It’s the absolute path the bundle mounts at on your Airflow components, and it’s how Astro identifies the bundle. It can’t overlap /usr/local/airflow/dags.
  • --non-dags-bundle-type is a free-form label, such as dbt. It defaults to none.
A new non-Dag bundle is served alongside main unless you associate it with other Dag bundles. To change the association after the first deploy, update the bundle rather than redeploying it. You can also register a non-Dag bundle before you deploy to it. In the Astro UI, click Bundles, click Non-Dag, then click New non-Dag bundle and set its Mount path and Served alongside bundles. The bundle stays empty until your first deploy to that mount path. To deploy a dbt project with the dedicated dbt commands instead, see Deploy dbt projects to Astro.

​
View the bundles on a Deployment

  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Bundles.
  3. Click Dag or Non-Dag.
Dag lists each Dag bundle with its Name, Description, Version, and Last deploy. The bundle named main carries a Default badge.Non-Dag lists each non-Dag bundle with its Mount path, Type, Description, Served alongside Dag bundles, Version, and Last deploy.A bundle that’s still rolling out shows a Deploying badge next to its version. A bundle you’ve deleted shows Deletion pending until your Deployment finishes removing it.
To confirm which bundle a Dag came from, open the Dag in the Airflow UI, click Details, then find Bundle Name under Latest Dag Version.

​
Change which Dag bundles serve a non-Dag bundle

Set the complete list of Dag bundles you want the non-Dag bundle served alongside. The new list replaces the existing one and can’t be empty.
  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Bundles, then click Non-Dag.
  3. Open the actions menu for the bundle, then click Edit bundle.
  4. Change Served alongside, then click Save.
You can also update any bundle’s description:
A description is the only field you can change on a Dag bundle. Bundle names and mount paths are fixed after you create them.

​
Delete a bundle

Deleting a Dag bundle stops Astro from serving its Dags to your Deployment. Airflow might then drop the Dag records for those Dags, and task runs still in flight might fail. Deleting a non-Dag bundle removes its files from the Airflow components that served it. Neither deletes your source code.
On Astro Runtime 3.0-1 through 3.2-4, Airflow doesn’t remove a deleted bundle’s Dag records automatically. Remove them manually after you delete the bundle.
  1. In the Astro UI, click Deployments, then select a Deployment.
  2. Click Bundles, then click Dag or Non-Dag.
  3. Open the actions menu for the bundle you want to delete, then click Delete bundle.
  4. Enter the bundle’s name, or its mount path for a non-Dag bundle, then click Delete bundle.
Two rules apply:
  • You can’t delete main.
  • You can’t delete a Dag bundle if that would leave a non-Dag bundle with no Dag bundle to be served alongside. Associate those non-Dag bundles with another Dag bundle, or delete them, first.
A deleted bundle stays visible with a pending-deletion state until your Deployment finishes removing it.

​
Limits and requirements

​
Dag IDs must be unique across bundles

Airflow identifies a Dag by its Dag ID alone, so a Dag ID must be unique across every bundle on a Deployment, not only within one bundle. If the same Dag ID exists in two bundles, the bundle that parsed most recently wins. That can change from one parse to the next, so the Dag can alternate between bundles. Any consistent behavior you observe isn’t guaranteed to continue. On Airflow 3.4 and later, Airflow also records a duplicate Dag ID warning naming the other file and bundle. Before you split code into bundles, check that you don’t have duplicate Dag IDs across the repositories you’re splitting.

​
Deploy history and rollbacks

Each bundle deploy is its own entry in your Deployment’s deploy history, recording which bundle it changed. See Deploy history and rollbacks. Rollbacks apply to the whole Deployment, not to one bundle. Rolling back returns every bundle to the state captured in the deploy you select, which means:
  • Bundles that changed after that deploy return to their earlier versions.
  • Bundles you created after that deploy are deleted.
  • Bundles you deleted after that deploy are restored.
Before the rollback runs, the confirmation lists every bundle it affects under Bundles affected, and every bundle it removes under Bundles to be deleted.

​
See also