This is an automated email from the ASF dual-hosted git repository.
jscheffl pushed a commit to branch v3-2-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v3-2-test by this push:
new 032a8914b15 [v3-2-test] Docs: Expand Helm Chart upgrade tasks in
Airflow 3 migration guide (#66118) (#66259)
032a8914b15 is described below
commit 032a8914b1522edf439a5899d3b71443ce4f8969
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Sat May 2 17:25:43 2026 +0200
[v3-2-test] Docs: Expand Helm Chart upgrade tasks in Airflow 3 migration
guide (#66118) (#66259)
* [v3-2-test] Docs: Expand Helm Chart upgrade tasks in Airflow 3 migration
guide (#66118)
* Docs: Expand Helm Chart upgrade tasks in Airflow 3 migration guide
Replace the two-line Helm Chart note in the Airflow 3 migration guide
with a dedicated subsection that lists the concrete action items for
upgrading the official chart from Airflow 2.x to 3.x: webserver to
apiServer rename with a values.yaml before/after, secret_key relocation,
jwtSecretName, the standalone dagProcessor deployment, FabAuthManager
default, webserver_config.py rework, minimum Kubernetes 1.30, the DB
migration job, and a pointer to the chart release notes for renamed and
removed keys.
Signed-off-by: André Ahlert <[email protected]>
* Move Helm Chart upgrade tasks to chart/docs
Address review from @Miretpl: chart-specific upgrade content belongs
under chart/docs, mirroring the providers/fab/docs/upgrading.rst pattern
where each component owns its upgrade guide and the core migration guide
links to it.
Move the expanded Helm Chart upgrade checklist from
airflow-core/docs/installation/upgrading_to_airflow3.rst to a new
chart/docs/upgrading-to-airflow-3.rst, restore the original two-line
note in the core guide, and add a pointer to the chart doc from the
core guide. Register the new file in chart/docs/index.rst under Guides.
Signed-off-by: André Ahlert <[email protected]>
---------
(cherry picked from commit 8fc246721e5f348c43e8c3176d06aad9ead18f2e)
Co-authored-by: André Ahlert <[email protected]>
Signed-off-by: André Ahlert <[email protected]>
* Upgrade uv.lock
---------
Signed-off-by: André Ahlert <[email protected]>
Co-authored-by: André Ahlert <[email protected]>
Co-authored-by: Jens Scheffler <[email protected]>
---
.../docs/installation/upgrading_to_airflow3.rst | 1 +
chart/docs/index.rst | 1 +
chart/docs/upgrading-to-airflow-3.rst | 119 +++++++++++++++++++++
uv.lock | 4 +-
4 files changed, 124 insertions(+), 1 deletion(-)
diff --git a/airflow-core/docs/installation/upgrading_to_airflow3.rst
b/airflow-core/docs/installation/upgrading_to_airflow3.rst
index ad0b5507b62..683779c63c2 100644
--- a/airflow-core/docs/installation/upgrading_to_airflow3.rst
+++ b/airflow-core/docs/installation/upgrading_to_airflow3.rst
@@ -317,6 +317,7 @@ and FastAPI middlewares (``fastapi_root_middlewares``).
If you use the Airflow Helm Chart to deploy Airflow, please check your defined
values against configuration options available in Airflow 3.
All configuration options below ``webserver`` need to be changed to
``apiServer``. Consider that many parameters have been renamed or removed.
+For the full chart-specific upgrade checklist (``values.yaml`` changes, the
standalone Dag processor, JWT secret, FAB defaults, minimum Kubernetes version,
and renamed keys across chart ``1.16.0``..``1.18.0``), see
:doc:`helm-chart:upgrading-to-airflow-3`.
Step 7: Changes to your startup scripts
---------------------------------------
diff --git a/chart/docs/index.rst b/chart/docs/index.rst
index 286183e1d15..0b31b45e91c 100644
--- a/chart/docs/index.rst
+++ b/chart/docs/index.rst
@@ -45,6 +45,7 @@ Helm Chart for Apache Airflow
production-guide
service-account-token-examples
+ upgrading-to-airflow-3
.. toctree::
:hidden:
diff --git a/chart/docs/upgrading-to-airflow-3.rst
b/chart/docs/upgrading-to-airflow-3.rst
new file mode 100644
index 00000000000..312bceb8028
--- /dev/null
+++ b/chart/docs/upgrading-to-airflow-3.rst
@@ -0,0 +1,119 @@
+ .. 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 ``1.16.0`` or later (chart
``1.16.0`` is the first release that
+supports Airflow 3) and review your ``values.yaml`` against the items below.
Many keys have been renamed, removed,
+or replaced and the chart will 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. The chart
ships with a 3.x default starting at
+chart ``1.17.0``.
+
+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:``. The component now
+listens on port ``8080`` and is started with ``airflow api-server``. 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 install. 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 workers and triggerers
+start.
+
+Deploy the standalone Dag processor
+-----------------------------------
+
+In Airflow 3 the Dag file 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 new component, including granting its ServiceAccount access
to your Dag bundles (git-sync,
+persistent volumes, or custom bundles).
+
+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.17.0`` raised the minimum supported Kubernetes version to ``1.30``.
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 ``1.16.0``..``1.18.0``. 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``.
diff --git a/uv.lock b/uv.lock
index b23921c100d..7c8b8a54b29 100644
--- a/uv.lock
+++ b/uv.lock
@@ -97,9 +97,9 @@ apache-airflow-providers-mongo = false
apache-airflow-providers-apprise = false
apache-airflow-providers-apache-impala = false
apache-airflow-ctl = false
+apache-airflow-providers-zendesk = false
apache-airflow-providers-github = false
apache-airflow-providers-snowflake = false
-apache-airflow-providers-zendesk = false
apache-airflow-providers-presto = false
apache-airflow-providers-airbyte = false
apache-airflow-providers-apache-hive = false
@@ -7797,6 +7797,7 @@ source = { editable = "dev/registry" }
dependencies = [
{ name = "pydantic" },
{ name = "pyyaml" },
+ { name = "tomli", marker = "python_full_version < '3.11'" },
]
[package.dev-dependencies]
@@ -7808,6 +7809,7 @@ dev = [
requires-dist = [
{ name = "pydantic", specifier = ">=2.12.0" },
{ name = "pyyaml", specifier = ">=6.0.3" },
+ { name = "tomli", marker = "python_full_version < '3.11'", specifier =
">=2.0.0" },
]
[package.metadata.requires-dev]
