Upgrade Astro Runtime

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.

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​

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​

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.

   To upgrade to the latest version of Runtime, for example, change the FROM statement in your Dockerfile to:

   FROM quay.io/astronomer/astro-runtime:12.8.0
   

   You must always specify the major, minor, and patch version of any given Astro Runtime version.

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.

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.

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 a full collection of Astro Runtime Docker images, go to the Astro Runtime repository on Quay.io.

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.

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.

   info

   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.

Version upgrade considerations​

This is where you'll find the upgrade considerations for specific Astro Runtime versions. This includes breaking changes, database migrations, and other considerations.

Runtime 3.0 (Airflow 3.0)​

Runtime 3.0-2​

The Remote Execution Agent based on Airflow 3.0-1 has a known incompatibility with the Astro Runtime 3.0-2. If you use remote execution, do not upgrade to or create Remote Deployments that use the combination of Runtime Execution Agent 1.0.0 and Astro Runtime 3.0-2. A fix for the incompatibility will be released in Astro Runtime v3.0-3.

If you created a new remote Deployment with 3.0-2, you cannot rollback to 3.0-1. You must either create a new remote Deployment with 3.0-1 or wait until the 3.0-3 patch and then upgrade.

If you upgraded a Deployment from 3.0-1 to 3.0-2, Astronomer advises you to downgrade your Deployments or rollback to 3.0-1 by using a Dockerfile change or by rolling back your Deployment in the Astro UI.

• Roll back to previous deploys
• Roll back Deployments after a broken upgrade

Runtime 12 (Airflow 2.10)​

Upgrade to Python 3.12​

Starting with Python version 3.12, Python has removed the module imp. This can cause errors for your DAGs if you use imp to access materials using the import statement. Python recommends migrating to importlib instead.

See How do I migrate from imp guidance from Python for remediation steps.

Runtime 11 (Airflow 2.9)​

Restricted versions of Runtime 11​

You cannot create new Deployments or upgrade to the following versions of Runtime 11, which are yanked. These restricted runtime versions prevent you from upgrading to or creating a Deployment with a version that contains a known limitation or bug.

• 11.0.0
• 11.1.0

Bug affecting users running a local Astro Runtime environment​

In Airflow 2.9, a bug affecting custom actions in Airflow plugins (#39421) prevented users from running the Astro Runtime environment locally for Astro Runtime versions 11.0.0, 11.1.0, and 11.2.0. Deployments running these versions on Astro are not affected.

To continue using these versions of the Astro runtime locally, set AIRFLOW__ASTRONOMER__UPDATE_CHECK_INTERVAL=0 in your Astro project .env file.

Runtime 9 (Airflow 2.7)​

Restricted versions of Runtime 9​

You cannot create new Deployments or upgrade to the following versions of Runtime 9, which are yanked. These restricted runtime versions prevent you from upgrading to or creating a Deployment with a version that contains a known limitation or bug.

• 9.0.0
• 9.1.0
• 9.2.0
• 9.3.0
• 9.4.0
• 9.5.0
• 9.6.0

Connection testing in the Airflow UI disabled by default​

In Airflow 2.7, connection testing in the Airflow UI is disabled by default. Astronomer does not recommend reenabling the feature unless you fully trust all users with edit/ delete permissions for Airflow connections.

To reenable the feature, set the following environment variable in your Astro project Dockerfile:

ENV AIRFLOW__CORE__TEST_CONNECTION=Enabled

Upgrade to Python 3.11​

The base distribution of Astro Runtime 9 uses Python 3.11 by default. Some provider packages, such as apache-airflow-providers-apache-hive, aren't compatible with Python 3.11.

To continue using these packages with a compatible version of Python, upgrade to the Astro Runtime Python distribution for your desired Python version.

Runtime 8 (Airflow 2.6)​

Astro Runtime version 8.0.0 is a restricted version of the Astro Runtime (yanked), which means you can't create Deployments on Astro with this runtime version. These restricted runtime versions prevent you from upgrading to or creating a Deployment with a version that contains a known limitation or bug.

Breaking change to apache-airflow-providers-cncf-kubernetes in version 8.4.0​

Astro Runtime 8.4.0 upgrades apache-airflow-providers-cncf-kubernetes to 7.0.0, which includes a breaking change by removing some deprecated features from KubernetesHook. If you are using any of these features, either pin your current version of apache-airflow-providers-cncf-kubernetes to your requirements.txt file or ensure that you don't use any of the deprecated features before upgrading.

Upgrade directly to Astro Runtime 8.1​

Astro Runtime 8.0 introduced a number of bugs and dependency conflicts which were subsequently fixed in Runtime 8.1. As a result, Astro Runtime 8.0 is not available in the Astro UI and no longer supported by Astronomer. To use Airflow 2.6, upgrade directly to Runtime 8.1.

Package dependency conflicts​

Astro Runtime 8 includes fewer default dependencies than previous versions. Specifically, the following provider packages are no longer installed by default:

• apache-airflow-providers-apache-hive
• apache-airflow-providers-apache-livy
• apache-airflow-providers-databricks
• apache-airflow-providers-dbt-cloud
• apache-airflow-providers-microsoft-mssql
• apache-airflow-providers-sftp
• apache-airflow-providers-snowflake

If your DAGs depend on any of these provider packages, add the provider packages to your Astro project requirements.txt file before upgrading. You can also pin specific provider package versions to ensure that none of your provider packages change after upgrading.

Upgrade to Python 3.10​

Astro Runtime 8 uses Python 3.10. If you use provider packages that don't yet support Python 3.10, use one of the following options to stay on Python 3.9:

• Run your tasks using the KubernetesPodOperator or PythonVirtualenvOperator. You can configure the environment that these tasks run in to use Python 3.9.
• Use the astronomer-provider-venv to configure a custom virtual environment that you can apply to individual tasks.

Provider incompatibilities​

There is an incompatibility between Astro Runtime 8 and the following provider packages installed together:

• apache-airflow-providers-cncf-kubernetes==6.1.0
• apache-airflow-providers-google==10.0.0

That can be resolved by pinning apache-airflow-providers-google==10.9.0 or greater in your requirements.txt file.

This incompatibility results in breaking the GKEStartPodOperator. This operator inherits from the KubernetesPodOperator, but then overrides the hook attribute with the GKEPodHook. In the included version of the cncf-kubernetes providers package, the KubernetesPodOperator uses a new method, get_xcom_sidecar_container_resources. This method is present in the KubernetesHook, but not the GKEPodHook. Therefore, when it is called it causes the task execution to break.

Runtime 6 (Airflow 2.4)​

Smart Sensors were deprecated in Airflow 2.2.4 and removed in Airflow 2.4.0. If your organization is still using Smart Sensors, you'll need to start using deferrable operators. See Deferrable operators.

Runtime 5 (Airflow 2.3)​

Astro Runtime 5.0.0, based on Airflow 2.3, includes changes to the schema of the Airflow metadata database. When you first upgrade to Runtime 5.0.0, consider the following:

• Upgrading to Runtime 5.0.0 can take 10 to 30 minutes or more depending on the number of task instances that have been recorded in the metadata database throughout the lifetime of your Deployment on Astro.

• Once you upgrade successfully to Runtime 5, you might see errors in the Airflow UI that warn you of incompatible data in certain tables of the database. For example:

  Airflow found incompatible data in the `dangling_rendered_task_instance_fields` table in your metadata database, and moved...
  

  These warnings have no impact on your tasks or DAGs and can be ignored. If you want to remove these warning messages from the Airflow UI, reach out to Astronomer support. If requested, Astronomer can drop incompatible tables from your metadata database.

For more information on Airflow 2.3, see "Apache Airflow 2.3.0 is here" or the Airflow 2.3.0 changelog.