Deploy Dags to Astro | Astronomer Documentation

Dag-only deploys are the fastest way to deploy code to Astro. They are recommended if you only need to deploy changes made to the dags directory of your Astro project.

Dag-only deploys are enabled by default on all Deployments on Astro Hosted. When they are enabled, you must still deploy your project image when you make a change to any file in your Astro project that is not in the dags directory, or when you upgrade Astro Runtime.

Dag-only deploys have the following benefits:

Dag-only deploys are significantly faster than project deploys.
Deployments pick up Dag-only deploys without restarting. This results in a more efficient use of workers and no downtime for your Deployments.
If you have a CI/CD process that includes both Dag and image-based deploys, you can use your repository’s permissions to control which users can perform which kinds of deploys. See Dag deploy templates for how you can set this up in your CI/CD pipelines.
You can use Dag deploys to update your Dags when you have slow upload speeds on your internet connection.

Trigger a Dag-only deploy

Triggering a Dag-only deploy pushes Dags to Astro and mounts them to the workers and schedulers in your Deployment. Dag-only deploys do not disrupt running tasks and do not cause any components to restart when you push code. If you deploy changes to a Dag that is currently running, active task runs finish executing according to the code from before you triggered a deploy. New task runs are scheduled using the code from your latest deploy.

Run the following command to deploy only your dags directory to a Deployment:

1 astro deploy --dags

When you run astro deploy --dags, all existing Dags in the Deployment are replaced by the new Dags that you are deploying. The deployment process replaces the entire Dag bundle with the new set of Dags, rather than incrementally adding or updating individual Dag files.

Unlike image deploys, Dag deploys do not include pytest as part of the deploy process by default. This means that Dag deploys might include faulty code that would otherwise be caught in an image deploy.

To have the same testing process in Dag deploys, run astro deploy --dags --pytest. Note that this can increase the time your deploys take. See Test your Astro project for more information about how to use the Astro CLI’s pytest features.

Trigger an image-only deploy

Even if you primarily use Dag-only deploys, you still need to occasionally make image deploys to update your Astro Runtime version or install dependencies. However, depending on your CI/CD strategy, triggering a full project deploy with astro deploy might affect your existing Dags.

When you trigger an image-only deploy, it builds every non-Dag file in your Astro project as a Docker image and deploys the image to all Airflow components in a Deployment. This includes your Dockerfile, plugins, and all Python and OS-level packages. Dags are not deployed, and your Deployment Dag folder and Dag bundle version are not affected. Because an image-only deploy ignores files in the dags directory during the Docker image build, it’s important to place any files needed for the build in an appropriate directory such as the include directory. See Airflow best practices for information on recommended file structure and other Dag writing best practices. Running the astro deploy --image command will also restart the Kubernetes Pods. Image-only deploys are only available when you have Dag-only deploys enabled.

Run the following command to build and deploy only your non-dag files to a Deployment:

1 astro deploy --image

If you use prebuilt Docker images for your image deploys, you can use both the --image-name and --image flags to update your image without updating your dags folder.

Enable or disable Dag-only deploys on a Deployment

If you have Workspace Owner permissions, you can enable or disable Dag-only deploys for a Deployment at any time. After you disable Dag-only deploys and trigger a code deploy:

Any changes to your Dag code are deployed as part of your Astro project Docker image.
In the Astro UI, your Deployment Dag bundle version doesn’t update when you deploy code.

To determine if turning off Dag-only deploy functionality is the right choice for your organization, contact Astronomer support.

Before you enable or disable Dag-only deploys on a Deployment, ensure the following:

You have access to the latest version of your Deployment’s Astro project.
You can update your Deployment using the Astro CLI.

Carefully read and complete all of the following steps to ensure that disabling or enabling Dag-only deploys doesn’t disrupt your Deployment. Immediately after you update the setting, you must trigger an image deploy to your Astro Deployment using astro deploy. If you don’t complete this step, you can’t access your Dags in the Airflow UI.

Prerequisites

Before you enable or disable Dag-only deploys on a Deployment, ensure the following:

You have Workspace Owner permissions for the Workspace that hosts the Deployment.
You have access to the latest version of your Deployment’s Astro project.
You can update your Deployment using the Astro CLI.

Enable Dag-only deploys

Dag-only deploys are enabled by default on Astro Hosted. While enabled:

You can run astro deploy --dags to deploy only Dags to your Deployment.
In the Astro UI, your Deployment Dag bundle version updates when you trigger an image deploy or a Dag-only deploy.
When you only deploy Dags, it doesn’t automatically upgrade your Runtime version. You must periodically complete a full image deploy to upgrade the Runtime version.
Your Deployment includes infrastructure for deploying your Dags separately from your project image. See What happens during a code deploy.

Run the following command to enable dag-only deploys:

1 astro deployment update --dag-deploy enable

Run the following command to deploy all of the files in your Astro project as a Docker image:

1 astro deploy

Disable Dag-only deploys

After you disable Dag-only deploys:

You can’t run astro deploy --dags to trigger a Dag-only deploy to your Deployment.
Any changes to your Dag code are deployed as part of your Astro project Docker image.
In the Astro UI, your Deployment Dag bundle version doesn’t update when you deploy code.
Your Deployment doesn’t include infrastructure for deploying your Dags separately from your project image. See What happens during a code deploy.

Run the following command to disable dag-only deploys:

1 astro deployment update --dag-deploy disable

Run the following command to deploy all of the files in your Astro project as a Docker image:

1 astro deploy