.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

.. http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Upgrading the Helm Chart to Airflow 3

Before reading this, make sure you have read the Airflow Upgrade Guide for how to prepare for an upgrade: :doc:apache-airflow:installation/upgrading_to_airflow3.

This guide describes the chart-specific tasks for upgrading a deployment of the official Airflow Helm chart from Airflow 2.x to Airflow 3.x. Upgrade the chart to at least 1.19.0 version and review your values.yaml against the items below. Many keys have been renamed, removed, or replaced within the chart and the chart may fail to render or deploy unsupported components silently if old keys remain.

Bump the Airflow image

Set defaultAirflowTag and airflowVersion to a 3.x release.

Rename webserver to apiServer

The Airflow 3 component that serves the UI and the public REST API is the API server, not the webserver. All configuration that lived under webserver: in the chart values must move under apiServer:. For example:

.. code-block:: yaml

Airflow 2.x chart values

webserver: replicas: 2 service: type: ClusterIP resources: {}

Airflow 3.x chart values

apiServer: replicas: 2 service: type: ClusterIP resources: {}

Move the secret key

The API server reads [api] secret_key instead of [webserver] secret_key. If you set this through config: in your values file or through extraEnv, update the section name.

Add a JWT secret

Airflow 3 uses short-lived JWT tokens to authenticate workers and triggerers against the API server. The chart generates a jwt-secret Secret on every install/update operation. If you template Secrets out-of-band or pin a custom name through jwtSecretName, make sure the referenced Secret exists with a jwt-secret key before Airflow components start.

Deploy the standalone Dag Processor

In Airflow 3 the Dag Processor is no longer embedded in the scheduler. The chart deploys it as a separate dag-processor Deployment configured under dagProcessor:. Review resources, tolerations, and any RBAC overrides for this component, including granting its Service Account access to your Dags code.

Pick an auth manager

The chart defaults to FabAuthManager (provided by the apache-airflow-providers-fab package) so that existing FAB-based users, roles, and SSO configuration keep working. If you migrated to a different auth manager, set it explicitly under config.core.auth_manager and ensure the corresponding provider is installed in your image.

Rework custom plugins

If you mount a webserver_config.py or ship Flask-AppBuilder plugins (appbuilder_views, appbuilder_menu_items, flask_blueprints), install the FAB provider and mount the file under the apiServer section instead of webserver. See the plugin notes in the core :doc:apache-airflow:installation/upgrading_to_airflow3 guide and :doc:apache-airflow-providers-fab:upgrading for details.

Check the minimum Kubernetes version

Chart 1.19.0 supports 1.30+ Kubernetes version. Upgrade your cluster before upgrading the chart if needed.

Run database migrations as part of the upgrade

The chart's database migration job handles airflow db migrate automatically when you run helm upgrade. Make sure the migration job completes successfully before traffic is sent to the new API server. If you disable the built-in job, run airflow db migrate yourself before scaling up the scheduler, API server, Dag processor, and triggerer.

Re-check renamed or removed values

Many configuration options under webserver/apiServer, workers, and scheduler were renamed or removed across chart versions. Diff your existing values.yaml against the chart's default values.yaml and the :doc:release_notes for those versions before applying.

After updating values.yaml, render the chart locally with helm template and inspect the diff against your current release before running helm upgrade.