This feature is only available for Airflow 3.x Deployments.
Astro Remote Execution Agent versions are released regularly and use semantic versioning. Astronomer ships major, minor, and patch releases of the Remote Execution Agent in the format of major.minor.patch. Each previous minor version is maintained for 6 months from its initial .0 release, during which it receives only critical security (CVE) fixes — not bug fixes. CVE backports use the latest available patch release of Runtime for each Airflow x.y.z version.
Bug fixes are delivered through new minor.patch versions on the latest minor release. If you report an issue with a maintained Astro Runtime image that isn’t on the latest minor.patch version, Astronomer support may ask you to upgrade to see if it resolves the issue. Because minor versions are backward compatible, upgrading to the latest minor is the supported path for resolving bugs.
New Astro Runtime release images are built only for the latest minor agent release. When a new Runtime version is released, it is paired with the current latest minor agent version. If the new Runtime requires major functional agent changes, Astronomer releases a new minor agent version to ship with it.
Critical security (CVE) fixes are backported to previous minor versions still within their 6-month maintenance window. CVE backports use the latest available Runtime patch release for each supported Airflow x.y.z version.
You can find full information about releases in the Remote Execution Agent release notes.
The following examples illustrate how the policy applies. Assume agent v1.6.0 on Runtime 3.2-2 with Python 3.14 is the current latest publicly available minor.patch version.
The following table describes the naming conventions for the image tags, allowing you to specify particular versions or allow your environment to use the latest options. Astronomer recommends using a fixed tag, with the versions for the Runtime, Python, and Remote Execution Agent explicitly defined.
As of May 2026, the Remote Execution Agent Helm chart is versioned independently from the Remote Execution Agent. This allows Astronomer to make changes to the Helm chart independently from Remote Execution releases, while still maintaining compatibility with supported agent versions. Decoupling the Helm chart from the Remote Execution Agent release lets Astronomer ship Helm chart bug fixes and enhancements faster.
Each new Helm Chart version will also have an appVersion field, populated with the Remote Execution agent version that the chart is shipping with by default.
What this means for you:
With this separation between Astro Agent and Helm Chart, you will need to check the compatibility between the Chart’s version and the Agent version you are running. See the compatibility matrix below.
Upgrading from Helm chart 1.x to 2.0.0 is a breaking change that requires action before you run helm upgrade. The label selectors on worker deployments and services changed in 2.0.0, and Kubernetes label selectors are immutable, so an in-place upgrade fails with the following error:
Complete the following actions in order before you upgrade:
Update your values.yaml file to the v2 format. Download the latest values.yaml file from the Astro UI and compare it with your current file. Astronomer recommends updating your values to reflect the new defaults. For example, sentinel.enabled is now true by default in 2.0.0. The v2 chart also removes all nullable fields, so any field in the format key: ~ must be removed, commented out, or set to a valid value.
Delete worker deployments and services. Run the following commands, replacing <namespace> with your agent namespace:
This causes an interruption of a few seconds to worker pods. Dag processing and triggerer components are unaffected. After deletion, run helm upgrade to re-create the worker deployments and services with the correct label selectors.
The Remote Execution Agent is distributed as a Docker image through the Astro control plane registry, images.astronomer.cloud, and includes a Runtime image with multi-Python version support for the Agent and your Dag processor. This allows you to run an image in the Execution Plane with all requirements for running Dag code and the program used by the Agent. It also means that there are three foundational components in your execution plane that can be upgraded to ensure your Remote Execution Agent works with the most up-to-date versions of Airflow and Astro resources:
The Remote Execution Agents in the Execution Plane must always use an image with a Runtime version that is less than or equal to the Astro Runtime version in the Orchestration Plane. In general, Astro Runtime versions are backward compatible with Remote Execution Agent versions. If an incompatibility exists, you can find it listed in Version upgrade considerations.
Astronomer recommends upgrading your Orchestration plane, your Astro Runtime, and Execution plane, your Remote Execution Agent, separately.
For upgrading the Execution Plane, Astronomer also recommends upgrading the agent version, the Astro Runtime version, and the Python version individually.
Update your Astro project Dockerfile with the new version of Astro Remote Execution Agent image.
Build your image and publish to your image registry.
Update your Remote Execution Agent’s Helm values.yaml file with the location of your new image in your image registry for the following parameters. To use the same image for all components, specify the image at the top level so all components inherit it. To use different images for different components, for example for each worker queue, specify the image for each component individually to override the top-level image.
Run the following helm commands to upgrade your installation:
To use a specific version of the Remote Execution Agent Helm chart, specify it with the --version flag in the helm upgrade command. If you don’t specify a version, the upgrade uses the latest available chart version after running helm repo update.
The following sections include upgrade considerations for specific Astro Remote Execution Agent versions. This includes breaking changes, database migrations, incompatibilities, and other considerations.
If a version isn’t included in this section, then there are no specific upgrade considerations for that version.
The Remote Execution Agent based on Airflow 3.0-1 has a known incompatibility with the Astro Runtime 3.0-2. Don’t upgrade to or create Remote Deployments that use the combination of an Orchestration Plane version 3.0-2 and Remote Execution Agent version using Runtime 3.0-1.