Skip to content

Chart: Support Helm template expressions in podAnnotations #63019

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jscheffl merged 5 commits into from
Mar 9, 2026
Merged

Chart: Support Helm template expressions in podAnnotations #63019

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
078a615
Support Helm template expressions in podAnnotations
XD-DENG Mar 6, 2026
530cf87
Rename chart newsfragment to PR number 63019
XD-DENG Mar 6, 2026
cc862db
Fix doc nits in customizing-labels: trim underlines and clarify api-s…
XD-DENG Mar 9, 2026
075fed6
Address doc structure: add Customizing Pod Labels subsection under um…
XD-DENG Mar 9, 2026
a4ab5d1
Merge branch 'main' into feat/helm-pod-annotations-tpl
XD-DENG Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 70 additions & 4 deletions chart/docs/customizing-labels.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,16 @@
specific language governing permissions and limitations
under the License.

Customizing Labels for Pods
===========================
Customizing Labels and Annotations for Pods
===========================================

Customizing Pod Labels
----------------------

The Helm Chart allows you to customize labels for your Airflow objects. You can set global labels that apply to all objects and pods defined in the chart, as well as component-specific labels for individual Airflow components.

Global Labels
-------------
~~~~~~~~~~~~~

Global labels can be set using the ``labels`` parameter in your values file. These labels will be applied to all Airflow objects and pods defined in the chart:

Expand All @@ -32,7 +35,7 @@ Global labels can be set using the ``labels`` parameter in your values file. The
environment: production

Component-Specific Labels
-------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~

You can also set specific labels for individual Airflow components, which will be merged with the global labels. Component-specific labels take precedence over global labels, allowing you to override them as needed.

Expand All @@ -59,3 +62,66 @@ For example, to add specific labels to different components:
apiServer:
labels:
role: ui

Customizing Pod Annotations
---------------------------

Pod annotations can be customized similarly to labels using ``podAnnotations`` and ``airflowPodAnnotations``.

Global Pod Annotations
~~~~~~~~~~~~~~~~~~~~~~

Global pod annotations can be set using ``airflowPodAnnotations``. These are applied to all Airflow component pods (scheduler, api-server/webserver, triggerer, dag-processor and workers):

.. code-block:: yaml
:caption: values.yaml

airflowPodAnnotations:
example.com/team: data-platform

Component-Specific Pod Annotations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Each component also supports its own ``podAnnotations``. Component-specific annotations take precedence over global ones:

.. code-block:: yaml
:caption: values.yaml

scheduler:
podAnnotations:
example.com/component: scheduler

Templated Pod Annotations
~~~~~~~~~~~~~~~~~~~~~~~~~

Both ``airflowPodAnnotations`` and ``podAnnotations`` support Helm template expressions. This allows annotations to reference release metadata or compute checksums of chart-managed resources, so that pods automatically restart when those resources change.

For example, to restart scheduler pods whenever the chart's extra ConfigMaps change:

.. code-block:: yaml
:caption: values.yaml

extraConfigMaps:
my-listener-config:
data: |
listener.py: ...

scheduler:
podAnnotations:
checksum/extra-configmaps: '{{ include (print $.Template.BasePath "/configmaps/extra-configmaps.yaml") . | sha256sum }}'

You can also reference release metadata:

.. code-block:: yaml
:caption: values.yaml

airflowPodAnnotations:
release: '{{ .Release.Name }}'

.. note::

The ``include``/``sha256sum`` pattern only works for resources managed by this chart
(e.g., those created via ``extraConfigMaps`` or ``extraSecrets``).
For ConfigMaps or Secrets created outside the chart, consider using a tool like
`Stakater Reloader <https://github.com/stakater/Reloader>`__ to trigger pod restarts
automatically.
2 changes: 1 addition & 1 deletion chart/files/pod-template-file.kubernetes-helm-yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ metadata:
{{- mustMerge .Values.workers.labels .Values.labels | toYaml | nindent 4 }}
{{- end }}
annotations:
{{- toYaml $podAnnotations | nindent 4 }}
{{- tpl (toYaml $podAnnotations) . | nindent 4 }}
{{- if or .Values.workers.kubernetes.kerberosInitContainer.enabled .Values.workers.kerberosInitContainer.enabled }}
checksum/kerberos-keytab: {{ include (print $.Template.BasePath "/secrets/kerberos-keytab-secret.yaml") . | sha256sum }}
{{- end }}
Expand Down
1 change: 1 addition & 0 deletions chart/newsfragments/63019.feature.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Support Helm template expressions in ``podAnnotations`` and ``airflowPodAnnotations`` values.
4 changes: 2 additions & 2 deletions chart/templates/api-server/api-server-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,10 +91,10 @@ spec:
checksum/jwt-secret: {{ include (print $.Template.BasePath "/secrets/jwt-secret.yaml") . | sha256sum }}
{{- end }}
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 8 }}
{{- end }}
{{- if .Values.apiServer.podAnnotations }}
{{- toYaml .Values.apiServer.podAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.apiServer.podAnnotations) . | nindent 8 }}
{{- end }}
spec:
{{- if .Values.apiServer.hostAliases }}
Expand Down
4 changes: 2 additions & 2 deletions chart/templates/cleanup/cleanup-cronjob.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,10 +67,10 @@ spec:
{{- end }}
annotations:
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 12 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 12 }}
{{- end }}
{{- if .Values.cleanup.podAnnotations }}
{{- toYaml .Values.cleanup.podAnnotations | nindent 12 }}
{{- tpl (toYaml .Values.cleanup.podAnnotations) . | nindent 12 }}
{{- end }}
spec:
restartPolicy: Never
Expand Down
4 changes: 2 additions & 2 deletions chart/templates/dag-processor/dag-processor-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,10 @@ spec:
cluster-autoscaler.kubernetes.io/safe-to-evict: "true"
{{- end }}
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 8 }}
{{- end }}
{{- if .Values.dagProcessor.podAnnotations }}
{{- toYaml .Values.dagProcessor.podAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.dagProcessor.podAnnotations) . | nindent 8 }}
{{- end }}
spec:
{{- if .Values.dagProcessor.priorityClassName }}
Expand Down
4 changes: 2 additions & 2 deletions chart/templates/database-cleanup/database-cleanup-cronjob.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,10 +67,10 @@ spec:
{{- end }}
annotations:
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 12 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 12 }}
{{- end }}
{{- if .Values.databaseCleanup.podAnnotations }}
{{- toYaml .Values.databaseCleanup.podAnnotations | nindent 12 }}
{{- tpl (toYaml .Values.databaseCleanup.podAnnotations) . | nindent 12 }}
{{- end }}
spec:
restartPolicy: Never
Expand Down
2 changes: 1 addition & 1 deletion chart/templates/flower/flower-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ spec:
checksum/airflow-config: {{ include (print $.Template.BasePath "/configmaps/configmap.yaml") . | sha256sum }}
checksum/flower-secret: {{ include (print $.Template.BasePath "/secrets/flower-secret.yaml") . | sha256sum }}
{{- if or (.Values.airflowPodAnnotations) (.Values.flower.podAnnotations) }}
{{- mustMerge .Values.flower.podAnnotations .Values.airflowPodAnnotations | toYaml | nindent 8 }}
{{- tpl (mustMerge .Values.flower.podAnnotations .Values.airflowPodAnnotations | toYaml) . | nindent 8 }}
{{- end }}
spec:
nodeSelector: {{- toYaml $nodeSelector | nindent 8 }}
Expand Down
4 changes: 2 additions & 2 deletions chart/templates/jobs/create-user-job.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,10 +66,10 @@ spec:
{{- if or .Values.airflowPodAnnotations .Values.createUserJob.annotations }}
annotations:
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 8 }}
{{- end }}
{{- if .Values.createUserJob.annotations }}
{{- toYaml .Values.createUserJob.annotations | nindent 8 }}
{{- tpl (toYaml .Values.createUserJob.annotations) . | nindent 8 }}
{{- end }}
{{- end }}
spec:
Expand Down
4 changes: 2 additions & 2 deletions chart/templates/jobs/migrate-database-job.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,10 +66,10 @@ spec:
{{- if or .Values.airflowPodAnnotations .Values.migrateDatabaseJob.annotations }}
annotations:
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 8 }}
{{- end }}
{{- if .Values.migrateDatabaseJob.annotations }}
{{- toYaml .Values.migrateDatabaseJob.annotations | nindent 8 }}
{{- tpl (toYaml .Values.migrateDatabaseJob.annotations) . | nindent 8 }}
{{- end }}
{{- end }}
spec:
Expand Down
2 changes: 1 addition & 1 deletion chart/templates/pgbouncer/pgbouncer-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ spec:
checksum/pgbouncer-config-secret: {{ include (print $.Template.BasePath "/secrets/pgbouncer-config-secret.yaml") . | sha256sum }}
checksum/pgbouncer-certificates-secret: {{ include (print $.Template.BasePath "/secrets/pgbouncer-certificates-secret.yaml") . | sha256sum }}
{{- if .Values.pgbouncer.podAnnotations }}
{{- toYaml .Values.pgbouncer.podAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.pgbouncer.podAnnotations) . | nindent 8 }}
{{- end }}
spec:
{{- if .Values.pgbouncer.priorityClassName }}
Expand Down
2 changes: 1 addition & 1 deletion chart/templates/redis/redis-statefulset.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ spec:
{{- if or .Values.redis.safeToEvict .Values.redis.podAnnotations }}
annotations:
{{- if .Values.redis.podAnnotations }}
{{- toYaml .Values.redis.podAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.redis.podAnnotations) . | nindent 8 }}
{{- end }}
{{- if .Values.redis.safeToEvict }}
cluster-autoscaler.kubernetes.io/safe-to-evict: "true"
Expand Down
4 changes: 2 additions & 2 deletions chart/templates/scheduler/scheduler-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,10 +109,10 @@ spec:
cluster-autoscaler.kubernetes.io/safe-to-evict: "true"
{{- end }}
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 8 }}
{{- end }}
{{- if .Values.scheduler.podAnnotations }}
{{- toYaml .Values.scheduler.podAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.scheduler.podAnnotations) . | nindent 8 }}
{{- end }}
spec:
{{- if .Values.scheduler.priorityClassName }}
Expand Down
2 changes: 1 addition & 1 deletion chart/templates/statsd/statsd-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ spec:
annotations:
checksum/statsd-config: {{ include (print $.Template.BasePath "/configmaps/statsd-configmap.yaml") . | sha256sum }}
{{- if .Values.statsd.podAnnotations }}
{{- toYaml .Values.statsd.podAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.statsd.podAnnotations) . | nindent 8 }}
{{- end }}
{{- end }}
spec:
Expand Down
4 changes: 2 additions & 2 deletions chart/templates/triggerer/triggerer-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,10 +93,10 @@ spec:
cluster-autoscaler.kubernetes.io/safe-to-evict: "true"
{{- end }}
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 8 }}
{{- end }}
{{- if .Values.triggerer.podAnnotations }}
{{- toYaml .Values.triggerer.podAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.triggerer.podAnnotations) . | nindent 8 }}
{{- end }}
spec:
{{- if .Values.triggerer.priorityClassName }}
Expand Down
4 changes: 2 additions & 2 deletions chart/templates/webserver/webserver-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,10 +92,10 @@ spec:
checksum/extra-configmaps: {{ include (print $.Template.BasePath "/configmaps/extra-configmaps.yaml") . | sha256sum }}
checksum/extra-secrets: {{ include (print $.Template.BasePath "/secrets/extra-secrets.yaml") . | sha256sum }}
{{- if .Values.airflowPodAnnotations }}
{{- toYaml .Values.airflowPodAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.airflowPodAnnotations) . | nindent 8 }}
{{- end }}
{{- if .Values.webserver.podAnnotations }}
{{- toYaml .Values.webserver.podAnnotations | nindent 8 }}
{{- tpl (toYaml .Values.webserver.podAnnotations) . | nindent 8 }}
{{- end }}
spec:
{{- if .Values.webserver.hostAliases }}
Expand Down
2 changes: 1 addition & 1 deletion chart/templates/workers/worker-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ spec:
checksum/extra-configmaps: {{ include (print $.Template.BasePath "/configmaps/extra-configmaps.yaml") . | sha256sum }}
checksum/extra-secrets: {{ include (print $.Template.BasePath "/secrets/extra-secrets.yaml") . | sha256sum }}
{{- if $podAnnotations }}
{{- toYaml $podAnnotations | nindent 8 }}
{{- tpl (toYaml $podAnnotations) . | nindent 8 }}
{{- end }}
spec:
{{- if .Values.workers.runtimeClassName }}
Expand Down
Loading
Loading