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.
  • Major versions are released for significant changes. Major versions aren’t guaranteed to be backward compatible.
  • Minor versions are released for new features and backward-compatible functional changes. Minor releases are backward compatible.
  • Patch versions are released for bug and security fixes. Patch releases are backward compatible.
Astronomer supports each major version of the Remote Execution Agent until the next major version is released. After a new major version is released, the previous major version continues to receive bug fixes and security patches for at least 12 months. All changes within a major version are backward compatible, but some releases require a newer Helm chart version or new configuration values. Before you upgrade, check the Helm chart compatibility matrix and Version upgrade considerations. You can find full information about releases in the Remote Execution Agent release notes.

​
Current major version

Remote Execution Agent 1.x is the current major version. Astronomer hasn’t released Remote Execution Agent 2.0.
Features, bug fixes, and security fixes ship as new releases of the current major version. If your agent version starts with 1., you can safely upgrade to the latest 1.x release. Astronomer recommends upgrading when new releases are available. Some new Astro Runtime versions require agent changes. In those cases, Astronomer releases a new agent version before the new Runtime version is supported on Remote Execution.

​
Previous major version

When Astronomer releases a new major version, the previous major version becomes the maintenance release. For at least 12 months after the new major version is generally available, releases of the maintenance version continue to include:
  • Critical security (CVE) fixes.
  • Critical bug fixes.
  • Rebuilt images for the Astro Runtime versions it already supports.
The maintenance release doesn’t receive new features or support for new Astro Runtime versions. After this period, the previous major version reaches end of life.

​
Control plane compatibility

The Astro control plane remains compatible with every supported major version of the Remote Execution Agent. Upgrading within a major version never requires a change to the control plane.

​
Transition from the 6-month maintenance policy

Previously, Astronomer maintained each Remote Execution Agent minor version for 6 months from its initial release. The following 1.x minor versions continue to receive critical security (CVE) fixes until their original 6-month window ends: Other earlier 1.x versions no longer receive fixes. Upgrade to the latest 1.x release.

​
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.

​
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.8.0

On Astro Runtime 3.3 and later images, agents don’t start until AIRFLOW__WORKERS__STATE_STORE_BACKEND is set. Helm chart 2.3.0 and later set it by default. On earlier charts, set it through commonEnv. See Configure state store backend.

​
Remote Execution Agent 1.2.0

Agents don’t start without a Sentinel authentication secret, which Helm chart 1.2.0 and later set. On earlier charts, upgrade the chart. On Agent Client 1.3.0 and later, you can instead set ASTRO_AGENT_CLIENT_SENTINEL_INTEGRATION_ENABLED=false through commonEnv.

​
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.