ReferenceRemote Execution Agent

Remote Execution Agent maintenance policy

Airflow 3
This 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 Remote Execution Agent minor version is maintained for 6 months from the release.

  • Major versions are released for significant feature additions. Major versions are not 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. Patch releases are backward compatible.

Bug fixes are delivered through new minor.patch versions. If you report an issue with a maintained Astro Runtime image that is not on the latest minor.patch version, Astronomer Support may ask you to upgrade to see if it resolves the issue.

You can find full information about releases in the Remote Execution Agent release notes.

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.

Tag FormatDescription
<runtime_version>-python-<python_version>-astro-agent-x.y.zRecommended configuration format. Fixed tag with specific Remote Execution Agent and Python versions
<runtime_version>Floating tag pointing to latest Remote Execution Agent and Python versions
<runtime_version>-python-<python_version>Floating tag pointing to latest Remote Execution Agent versions
<runtime_version>-baseBase image without ONBUILD support
<runtime_version>-python-<python_version>-baseFloating tag for base image without ONBUILD support
<runtime_version>-python-<python_version>-astro-agent-x.y.z-baseFixed tag with specific Remote Execution Agent and Python versions for base image
Remote Execution Agent images are not currently compatible with the RHEL platform.

Helm Chart Versioning

As of May 2026, the Remote Execution Agent Helm chart will be versioned independently from the Remote Execution Agent. This allows Astronomer to make some changes to the Helm chart independently from Remote Execution releases, while still maintaining compatibility with supported agent versions.

By decoupling from the Remote Execution Agent release Astronomer is now able to release bug fixes and enhancements to the Helm chart 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

Helm Chart VersionAstro Agent Version
1.5.01.3.0, 1.5.0
2.0.01.5.0 and above
Breaking change in Helm chart 2.0.0

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:

Error: UPGRADE FAILED: Deployment.apps "...-worker-..." is invalid: spec.selector: Invalid value: ... field is immutable

Complete the following actions in order before you upgrade:

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

  2. Delete worker deployments and services. Run the following commands, replacing <namespace> with your agent namespace:

    $kubectl delete deployment -l component=worker -n <namespace>
    $kubectl delete svc -l component=worker -n <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.

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 have backwards compatibility for Remote Execution versions. If an incompatibility exists, you can find them 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. If you want to use the same image for all components, you can specify the image at the top level and it will be used for all components. If you want to use different images for different components, for example for each worker queue, you can specify the image for each component individually to override the top-level image.

    1image: <image-url>

  4. Run the following helm commands to upgrade your installation:

    $helm repo update
    $helm upgrade astro-agent astronomer/astro-remote-execution-agent \
    >    --namespace astro-agent \
    >    --values values.yaml

    If you want to use a specific version of the Remote Execution Agent Helm chart, you can specify it with the --version flag in the helm upgrade command. If you don’t specify a version, it will upgrade using 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. Do not 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.