This feature is only available for Airflow 3.x Deployments.
Remote Execution Deployments require two sets of container images:
When using Remote Execution mode, the server (Deployment on Astro) and client (Remote Execution Agents) are deployed separately. You must maintain dedicated client images for the Remote Execution Agents. These client images are based on the Astro Remote Execution Agent image and must be pushed to a remote image registry accessible by your Agents.
Because these client images are distinct from the usual Astro Runtime images, you need to use dedicated commands to build and deploy them.
This guide explains how to initialize an Astro project for Remote Execution and how to build and push client images for Remote Execution Agents.
For details about Astro project image deploys with Remote Execution, see Deploy an Astro project.
For best practices and procedures to upgrade your Astro Runtime version, including for Remote Execution Deployments, see Upgrade Astro Runtime.
Run:
This generates the required files for building client images. If you omit --remote-image-repository, you can configure it later with:
Dockerfile.client – Dockerfile for client imagesrequirements-client.txt – Python dependencies for client imagespackages-client.txt – OS-level packages for client imagesSet up dag access for your Remote Execution Agents using either LocalDagBundle or GitDagBundle. Update your Agent’s Helm chart values.yaml accordingly. See Dag bundles.
Before you can deploy a client image, you must be logged in to your remote Docker registry. The Astro CLI does not manage authentication for your registry.
Log in using:
Replace <remote-registry> and <registry-username> with the details for your registry.
From your project directory, deploy the Astro Runtime image to your Remote Execution Deployment:
This command builds your project and pushes the updated Astro Runtime image to Astro, updating the Airflow components in your managed Astro Deployment.
Monitor the Deployment to confirm that the new version is running in the Astro UI.
The astro deploy command updates the orchestration plane only. To update the execution plane, follow the Remote Execution Agent image steps below.
From your project directory, run:
You can use additional flags as needed, such as:
By default, astro remote deploy builds an image for your computer’s platform. For example, if you are on a Mac with Apple silicon, it will build for linux/arm64. If your Agents need linux/amd64, the image may not work.
To avoid issues, always set the --platform flag: astro remote deploy --platform linux/amd64,linux/arm64
This command only pushes the client image to your remote registry. See astro remote for more information.
After pushing the image, you must update your Agent configuration to actually use it:
values.yaml.image field for each of the worker, dagProcessor, and triggerer component sections to the new client image reference (as just pushed).Agents will not use the new client image until this update is performed.
If you manage your Agent deployments via a CI/CD pipeline, update your pipeline to set the new client image in the Helm values.yaml file, and trigger the deployment process to roll out the change automatically. This ensures that updates to the client image are reliably applied across all agents without manual intervention.