Software: Upgrade Runtime

Overview

Regularly upgrading your Software Deployments ensures that your Deployments continue to be supported and that your Airflow instance has the latest features and functionality.

To upgrade your Airflow Deployment to a later version of Airflow:

• Select a new Airflow version with the Software UI or CLI to start the upgrade.
• Change the FROM statement in your project’s Dockerfile to reference an Astro Runtime image that corresponds to your current Airflow version.
• Deploy your upgrade to Astronomer.

Available Astronomer image versions

A cron job automatically pulls new Astronomer image versions from the Astronomer update service and adds them to the Software UI and CLI within 24 hours of their publication. You don’t have to upgrade Astronomer to upgrade Airflow.

If you don’t want to wait for new Astronomer image versions, you can manually trigger the cron job with the following Kubernetes command:

$
kubectl create job --namespace astronomer --from=cronjob/astronomer-houston-update-airflow-check airflow-update-check-first-run

If you get a message indicating that a job already exists, delete the job and rerun the command.

Upgrade considerations

Consider the following when you upgrade Astro Runtime:

• Astronomer does not support downgrading a Deployment on Astronomer Software to a lower version of 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.

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.

Step 1: Review upgrade considerations

Astro Runtime 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) Start the upgrade process

Now, by default, Astronomer Software uses the Runtime version that you configure in your Dockerfile in Step 5: Update your Astro Project. Prior to version 0.36, by default, you must first specify the Airflow and Runtime version you wanted to upgrade to, before starting your upgrade process.

If you want to use the prior workflow, you must change the feature flag, disableDesiredRuntimeVersion, in your Houston API values.yaml configuration to false:

1
astronomer:
2
    houston:
3
        config:
4
            deployments:
5
                disableDesiredRuntimeVersion: false

After you apply the configuration, you can start the upgrade process. Starting the upgrade process doesn’t interrupt or otherwise impact your Airflow Deployment. It only signals to Astronomer Software that you intend to upgrade at a later time.

With the Software UI

1. Go to Deployment > Settings > Basics > Airflow Version.
2. Select an Airflow version.
3. Click Upgrade.

With the Astro CLI

1. Run astro login <base-domain> to confirm you’re authenticated.

2. Run the following command to list your current Deployments.

   $
   astro deployment list

   Copy the ID of the Deployment you want to upgrade.

3. Run the following command to list the available Airflow versions:

   $
   astro deployment airflow upgrade --deployment-id=<deployment-id>

4. Enter the Airflow version you want to upgrade to and press Enter.

Step 3: (Optional) Pin provider package versions

Major Astro Runtime upgrades can include significant 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.

1. Run the following command to check the version of all provider packages installed in your Astro Runtime version:

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

2. 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 4: (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 5: Update your Astro project

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 example, to upgrade to the latest version of Runtime, you would change the FROM statement in your Dockerfile to:

   1
   FROM quay.io/astronomer/astro-runtime:13.2.0

   For a list of supported Astro Runtime versions, see Astro Runtime maintenance and lifecycle policy.

1. Save the changes to your Dockerfile.

Step 6: Test Astro Runtime locally

Astronomer recommends testing new versions of Astro Runtime locally to ensure that Airflow starts as expected before upgrading your 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 bottom of any page. You should see your new Astro Runtime version 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 experience 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 7: Deploy to Astronomer

1. Run the following command to push your upgraded Astro project to your Deployment:

   $
   astro deploy

2. In the Software UI, open your Deployment and 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.

Cancel Airflow upgrade

As a System Admin, you can cancel an Airflow Deployment upgrade at any time if you haven’t yet changed the Astronomer Runtime image in your Dockerfile and deployed it.

In the Software UI, select Cancel next to Airflow Version.

Using the Astro CLI, run:

$
astro deployment airflow upgrade --cancel --deployment-id=<deployment-id>

For example, if you cancel an upgrade from Airflow 2.1.0 to Airflow 2.2.0 in the CLI, the following message appears:

$
Airflow upgrade process has been successfully canceled. Your Deployment was not interrupted and you are still running Airflow 2.1.0.

Canceling the Airflow upgrade process does not interrupt or otherwise impact your Airflow Deployment or code that’s running.

1
astronomer:
2
  houston:
3
    config:
4
      deployments:
5
        enableSystemAdminCanCreateDeprecatedAirflows: true