Skip to main content
Airflow 3This feature is only available for Airflow 3.x Deployments.

​
Remote Execution Agent versioning

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.
  • Major versions are released for significant feature additions. Major versions aren’t guaranteed to be backward compatible.
  • Minor versions are released for functional changes. Minor releases are backward compatible.
  • Patch versions are released for bug and security fixes that resolve unwanted behavior in the latest minor version only. Patch releases are backward compatible. Previous minor versions in maintenance receive only critical security (CVE) fixes as patch releases.
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.

​
Release scenarios

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.

​
Image tag naming conventions

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.
Floating tags are frozen at v1.7.2Astronomer no longer updates the floating tags (<runtime_version>, <runtime_version>-python-<python_version>, and the -base variant of each). They stay pinned to the images from Remote Execution Agent v1.7.2, the most recent release that published them:
  • <runtime_version> and <runtime_version>-base point to the Python 3.12 images, <runtime_version>-python-3.12-astro-agent-1.7.2 and <runtime_version>-python-3.12-astro-agent-1.7.2-base.
  • <runtime_version>-python-<python_version> and <runtime_version>-python-<python_version>-base point to the v1.7.2 images for that Python version.
To upgrade, reference a fixed tag with the Runtime, Python, and Remote Execution Agent versions set explicitly, and change it when a new version is available.
Remote Execution Agent images aren’t currently compatible with the RHEL platform.

​
Helm chart versioning

As of April 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.

​
Helm chart to Astro agent compatibility matrix

For a version-by-version history of what changed in each Helm chart release, see Helm chart release notes.
Breaking change in Helm chart 2.0.0Upgrading from Helm chart 1.5.x to 2.0.0 is a breaking change that requires action before you run helm upgrade. See Helm chart upgrade guide: To 2.0.0 for the required steps.

​
Helm chart upgrade guide

This section lists the values.yaml file and Kubernetes changes required when upgrading the Remote Execution Agent Helm chart across a major version. If a chart version isn’t listed, no special upgrade steps are required beyond the standard helm upgrade process. See Helm chart release notes for the full history of chart changes.

​
To 2.0.0

Upgrading from Helm chart 1.5.x to 2.0.0 is a breaking change that requires action before you run helm upgrade.

​
Worker label selectors changed

The label selectors on worker Deployments and Services changed in 2.0.0 to include a per-worker label. Kubernetes label selectors are immutable, so an in-place upgrade fails with the following error:
Before you upgrade, delete the existing worker Deployments and Services. Replace <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.

​
Sentinel now enabled by default

sentinel.enabled changed from false to true. If you don’t want to run Sentinel, set sentinel.enabled: false explicitly in your values.yaml file before you upgrade. See Enable Sentinel monitoring.

​
Null values are no longer accepted for some optional fields

Chart 2.0.0 introduced stricter values validation. Optional fields that default to ~ (YAML null) in chart 1.5.x no longer accept null and must be a string, removed, or commented out. This affects the following fields, among others:
  • agentToken, agentTokenSecretName, agentTokenFile
  • imagePullSecretName, imagePullSecretData
  • sentinelAuthSecret, sentinelAuthSecretName, sentinelAuthSecretFile
  • openLineage.apiKey, openLineage.apiKeySecret, openLineage.namespace, openLineage.url
If your values.yaml file explicitly sets any of these fields to ~, helm install and helm template fail against the chart’s values schema. Remove the line, comment it out, or set it to a valid value before you upgrade. Fields you never set explicitly aren’t affected. Astronomer recommends downloading the latest values.yaml file from the Astro UI and comparing it with your current file before you upgrade.

​
Upgrade considerations

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:
  • Remote Execution Agent version
  • Runtime version, in your Orchestration Plane/Astro UI
  • Runtime version, in your Execution Plane/Agent image
  • Python version
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.

​
Remote Execution Agent image upgrade process

  1. Update your Astro project Dockerfile with the new version of Astro Remote Execution Agent image.
  2. Build your image and publish to your image registry.
  3. 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.
  4. 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.

​
Version upgrade considerations

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.

​
Remote Execution Agent 1.0.0

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.