Astro: Upgrade Runtime

Learn how to upgrade the Astro Runtime version on your Deployments. To take advantage of new features and bug and security fixes, upgrade Astro Runtime when a new version becomes available.

New versions of Astro Runtime are released regularly to support new Astro and Apache Airflow functionality. To take advantage of new features and bug and security fixes, Astronomer recommends upgrading Astro Runtime as new versions are available.

Prerequisites

• The Astro CLI.
• An Astro project.
• An Astro Deployment.

If you’re only upgrading a local Airflow environment, you don’t need an Astro Deployment and you can skip steps 7-8.

These instructions cover upgrading Astro Runtime versions within the same major Airflow version. For example, Airflow 2.x → 2.y or Airflow 3.x → 3.y. If you are upgrading from Airflow 2 to Airflow 3, follow the

Airflow 3 upgrade guide

instead..

Step 1: Review upgrade considerations

Astro upgrades can include breaking changes, especially when you’re upgrading to a new major version. Check the upgrade considerations for your upgrade version to anticipate any breaking changes or upgrade-specific instructions before you proceed.

Step 2: (Optional) Pin provider package versions [#pin-provider-package]

Major Astro Runtime upgrades can include major upgrades to built-in provider packages. These package upgrades can sometimes include breaking changes for your dags. See the Apache Airflow documentation for a list of all available provider packages and their release notes.

For the most stable upgrade path, Astronomer recommends pinning all provider package versions from your current Runtime version before upgrading. To check the version of all provider packages installed in your Runtime version, run:

docker run --rm quay.io/astronomer/astro-runtime:<current-runtime-version> pip freeze | grep apache-airflow-providers

After reviewing this list, pin the version for each provider package in your Astro project requirements.txt file. For example, Runtime 7.4.1 uses version 4.0.0 of apache-airflow-providers-databricks. To pin this version of the Databricks provider package when you upgrade to a later version of Runtime, you add the following line to your requirements.txt file:

apache-airflow-providers-databricks==4.0.0

Step 3: (Optional) Run upgrade tests with the Astro CLI

You can use the Astro CLI to anticipate and address problems before upgrading to a newer version of Astro Runtime. Before you upgrade, run the following command to run tests against the version of Astro Runtime you’re upgrading to:

astro dev upgrade-test --runtime-version <upgraded-runtime-version>

The Astro CLI then generates test results in your Astro project that identify dependency conflicts and import errors that you would experience using the new Astro Runtime version. Review these results and make the recommended changes to reduce the risk of your project generating errors after you upgrade. For more information about using this command and the test results, see Test before upgrade your Astro project.

Step 4: Update Your Dockerfile

These are instructions for upgrading minor versions on Airflow 2 or Airflow 3. For upgrading to Airflow 3, see the

Airflow 3 upgrade guide

.

1. In your Astro project, open your Dockerfile.
2. Change the Docker image in the FROM statement of your Dockerfile to a new version of Astro Runtime. For Airflow 2-based Runtimes, specify the major, minor, and patch version of Astro Runtime. For Airflow 3-based Runtimes, specify only the major and minor version. Exclude the patch version to automatically use the latest available patch.

Airflow version–specific Registry URLs

Airflow 2.x-based Runtime versions and Airflow 3.x-based Runtime versions have different registry URLs. See

Docker Registry URLs

for information on which URL to pull from.

3. Save the changes to your Dockerfile.

Step 5: Test Astro Runtime locally

Astronomer recommends testing new versions of Astro Runtime locally before upgrading a Deployment on Astro.

1. Open your project directory in your terminal and run astro dev restart. This restarts the Docker containers for the Airflow webserver, scheduler, triggerer, and Postgres metadata database.

2. Access the Airflow UI of your local environment by navigating to http://localhost:8080 in your browser.

3. Confirm that your local upgrade was successful by scrolling to the end of any page. The new Astro Runtime version is listed in the footer as well as the version of Airflow it is based on.

   

4. (Optional) Run dags locally to ensure that all of your code works as expected. If you encounter errors after your upgrade, it’s possible that your new Astro Runtime version includes a breaking provider package change. If you encounter one of these breaking changes, follow the steps in Upgrade or pin provider package versions to check your provider package versions and, if required, pin the provider package version from your previous Runtime version in your requirements.txt file.

Step 6: (Optional) Upgrade and test provider packages

If you pinned provider package versions before your upgrade, upgrade your provider packages by changing the pinned version in your requirements.txt file. Test each provider package upgrade locally before deploying to Astro.

Step 7: Deploy to Astronomer

To push your upgraded project to an Astro Deployment, run:

astro deploy

For more information about deploying to Astro, see Deploy code.

After you upgrade a Deployment on Astro to a new version of Astro Runtime, the only way to downgrade is to roll back to a previous deploy. If you attempt to downgrade a Deployment by updating your Dockerfile, the Astro CLI produces an error and your request to deploy does not succeed.

Generally speaking, Deployment rollbacks to lower Runtime versions are recommended only when your current code isn’t working as expected. This is because rollbacks to lower Runtime versions can result in your Deployment losing data from the metadata database. For more information, see What happens during a deploy rollback.

Step 8: Confirm your upgrade on Astro

1. In the Astro UI, select a Workspace, click Deployments, and then select a Deployment.

2. Click Open Airflow.

3. In the Airflow UI, scroll to the bottom of any page. You should see your new Runtime version in the footer:

   

   You will also see an Image tag for your deploy. This tag is shown only for Deployments on Astro and is not generated for changes in a local environment.

Step 9: (Remote Execution Deployments only) Upgrade Remote Execution Agents

If your Deployment uses Remote Execution, you must upgrade your Remote Execution Agents to a version compatible with your new Astro Runtime.

Agent and Runtime version compatibility is critical for Remote Execution Deployments. Always select an agent image that matches your Deployment’s Astro Runtime version, never newer. The Airflow version on Remote Execution Agents must be equal to or lower than the Airflow version configured for the orchestration plane.

1. Refer to the Remote Execution Agent release notes to identify the correct Agent version for your Astro Runtime version.
2. Find the base image tags in the Remote Execution Agent image reference.
3. Build and push an updated remote agent image, or pull a prebuilt image if suitable for your environment. For detailed instructions, see Build and deploy Remote Execution Agent images.
4. Update your Agent deployment. For example, modify the agent image reference in your Helm values.yaml file, then run a helm upgrade.
5. Confirm your agents are running the new version and healthy in the Astro UI.

For full upgrade and maintenance instructions, see Remote Execution Agents.

Upgrade considerations

Consider the following when you upgrade Astro Runtime:

• All versions of the Astro CLI support all versions of Astro Runtime. There are no dependencies between the two products.
• Upgrading to certain versions of Runtime might result in extended upgrade times or otherwise disruptive changes to your environment. To learn more, see Version-specific upgrade considerations.
• You can’t downgrade a Deployment on Astro to a lower version of Astro Runtime unless you roll back to a previous deploy.

To stay up to date on the latest versions of Astro Runtime, see Astro Runtime release notes. For more information on Astro Runtime versioning and support, see Astro Runtime versioning and lifecycle policy. For differences in Airflow 2.x-based Runtime versions and Airflow 3.x-based Runtime versions registry URLs, see Docker Registry URLs.

Run a deprecated Astro Runtime version

If you’re migrating to Astro from OSS Airflow or Astro Hybrid, where your Deployments run using an older version of Airflow or a deprecated version of the Astro Runtime, you can now use stepwise migration to complete your migration in stages. First, you can create Deployments with a deprecated version of the Astro Runtime using the Astro API to move to an Astro Hosted environment. Then, you can upgrade your code to the most up-to-date version of the Astro Runtime.

Deployments that run deprecated Astro Runtime versions will only receive support as Astro Runtime maintenance policy, and Astronomer might advise you to upgrade your runtime to the latest version of Astro to resolve performance issues or bugs. Runtime Version 4.2.9 is the lowest deprecated Runtime version that can be used with Astro.

When you choose a deprecated version of Astro Runtime, Astronomer recommends always choosing the latest patch version that includes your desired Airflow version. Some earlier patch versions of Astro Runtime include unexpected behavior and can’t be used even as a deprecated version. For more information about which versions are affected, see the

Version upgrade considerations

.

1. Contact your Astronomer account team and request the ability to run deprecated versions of Astro Runtime.
2. Create a Personal Access Token(PAT) to use for authentication to Astro.

You only need a PAT to create the first Deployment in your Organization running a deprecated version of Astro Runtime. You can then create all subsequent Deployments using either a Workspace or Organization API token with permissions to create a Deployment.

3. Create a Deployment using the Astro API. In your request, specify your PAT in the authorization header, and your deprecated Astro Runtime version using the astroRuntimeVersions property.

After you create the Deployment, you can manage the Deployment using any interface, including the Astro CLI and Astro UI. You can also create additional Deployments with deprecated Runtimes using the Astro API and either a Workspace or Organization API token.