Upgrade to Airflow 3

In-place upgrades are not supported. The workflows-3.0-airflow-3.1 version is based on a new major Airflow version and due to significant architectural changes not compatible to prior versions. You must provision a new instance, migrate your DAGs, and then delete the old instance.

Prerequisites

• You have a running STACKIT Workflows instance on version workflows-2.3-airflow-2.11.
• Your DAGs are stored in a Git repository accessible from STACKIT Workflows.
• You have reviewed the Apache Airflow 2 to 3 migration guide and updated your DAGs accordingly.

Key changes in Airflow 3

Before migrating, make sure your DAGs are compatible with Airflow 3:

• New import paths — Core decorators and classes have moved to airflow.sdk:

  # Airflow 2
  from airflow.decorators import dag, task
  
  # Airflow 3
  from airflow.sdk import dag, task

• Datasets renamed to Assets — Dataset is now Asset. Update your imports and usages:

  # Airflow 2
  from airflow.datasets import Dataset
  
  # Airflow 3
  from airflow.sdk import Asset

• Removed and deprecated APIs — Review the full list of breaking changes in the official Apache Airflow migration guide.

Migrate to Airflow 3

STACKIT Portal

1. Note the configuration of your existing instance.

   Before creating the new instance, collect all configuration values from your existing Workflows instance:

   1. On the sidebar click on Workflows. You can find it in the Data & AI category.
   2. Click on your existing instance to open the detail view.
   3. Note the following values:
      • Identity Provider: Client ID, Client secret, Scope, Discovery Endpoint
      • DAG repository: Repository URL, branch name, credentials
      • Monitoring: linked STACKIT Observability instance (if any)

2. Update your DAGs for Airflow 3 compatibility.

   In your DAG repository, apply the necessary code changes described in Key changes in Airflow 3 and push them to your repository branch.

   The new Workflows instance will immediately pick up the DAGs from the configured branch. Make sure your DAGs are compatible with Airflow 3 before proceeding.

3. Create a new Workflows instance with version workflows-3.0-airflow-3.1.

   1. On the sidebar click on Workflows.
   2. Click on Create Workflows.
   3. Fill in all required information using the values you noted in step 1. Set the version to workflows-3.0-airflow-3.1.
   4. Click on Order fee-based to create the instance.
   5. Wait for the new instance to reach the Active state.
   The instance status may change several times before reaching the Active state.

4. Validate the new instance.

   1. Open the Airflow UI of the new instance.
   2. Confirm that all DAGs from your repository are loaded correctly and show no import errors.
   3. Trigger a test run for your critical DAGs and verify they complete successfully.

5. Delete the old instance.

   Once you have confirmed that the new instance is working correctly, delete the old one:

   1. On the sidebar click on Workflows.
   2. On the right side click on the three dots menu next to your old workflows-2.3-airflow-2.11 instance and then on Delete.
   3. Enter the instance name as confirmation and click on Delete.

   Deleting the old instance is irreversible. All instance-specific metadata, including DAG run history and XCom values, will be lost.