Skip to main content
This feature is only available if you are on the Enterprise tier or above. See Astro Plans and Pricing.
Airflow 3This feature is only available for Airflow 3.x Deployments.
Remote Execution Deployments require two sets of container images:
  • Astro Runtime images: Astronomer’s managed distribution of Apache Airflow, powering all Deployments on Astro. This image runs in the orchestration plane.
  • Remote Execution Agent images: Specifically built for Remote Execution Agents. This image runs in the execution plane.
Astronomer builds and maintains the base images for Astro Remote Execution Agents. You should customize these images to include additional dependencies, such as Python packages or OS-level packages, required for your Dags to run in the execution plane. This guide explains how to initialize an Astro project and set up both images for Remote Execution.
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.

​
Prerequisites

You can build and push a Remote Execution Agent image before you register a Remote Execution Agent. astro remote deploy only requires your Remote Execution Deployment to exist.
  • A remote Docker registry accessible from the environment where your Remote Execution Agents run.

​
Build and deploy your Remote Execution project

1

Create a Remote Execution project

Run:
This generates the required files for building client images. If you omit --remote-image-repository, you can configure it later with:
2

Review generated files

  • Dockerfile.client – Dockerfile for client images
  • requirements-client.txt – Python dependencies for client images
  • packages-client.txt – OS-level packages for client images
3

Configure dag access

Set 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.
4

Sign in to your remote Docker registry

Before you can deploy a Remote Execution Agent image, you must be signed in to your remote image registry. The Astro CLI does not manage authentication for your registry.Sign in using:
Replace <remote-registry> and <registry-username> with the details for your registry.
5

Build and deploy the Astro Deployment image (orchestration plane)

From your project directory, deploy the Astro Runtime image to your Astro 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.
6

Build and deploy Remote Execution Agent (execution plane) images

From your project directory, run:
You can use additional flags as needed, such as:
Platform mismatch can cause build failuresBy 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
7

Update Remote Execution Agents to use the new image

After pushing the Agent image, you must update your Agent configuration to actually use it:
  1. Edit your Agent Helm chart values.yaml.
  2. Update the image field for each of the worker, dagProcessor, and triggerer component sections to the new client image reference (as just pushed).
  3. Apply the changes by running:
Agents will not use the new client image until this update is performed.
CI/CD pipelineIf 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.