Environment:Apache Airflow Kubernetes Helm Environment

Knowledge Sources	Apache Airflow Helm Chart Airflow Helm Chart Docs
Domains	Infrastructure, Kubernetes, Deployment
Last Updated	2026-02-08 20:00 GMT

Overview

Kubernetes 1.30+ cluster with Helm 3.10+ for deploying Airflow via the official Helm chart (v1.19.0) with Redis 7.2, PgBouncer 1.23.1, and git-sync v4.4.2.

Description

This environment defines the infrastructure requirements for deploying Apache Airflow on Kubernetes using the official Helm chart. The chart deploys Airflow as a set of Kubernetes resources including the scheduler, API server, workers, triggerer, and optional components (Flower, PgBouncer, StatsD exporter). The chart uses Helm API v2 (Helm 3+) and depends on the Bitnami PostgreSQL chart (v13.2.24) as an optional embedded database. Redis 7.2 is used for the Celery broker (pinned to 7.2 due to Redis licensing changes).

Usage

Use this environment for production Kubernetes deployments of Apache Airflow. This is the prerequisite for all Helm chart-based implementations including component scaling, DAG distribution, database configuration, and RBAC security configuration.

System Requirements

Category	Requirement	Notes
Kubernetes	>= 1.30	Minimum version bumped to 1.30 in chart 1.17.0
Helm	>= 3.10	Helm API v2 requires Helm 3.0+; 3.10+ recommended
PV Provisioner	Optional	Required for persistent logs and DAG storage
Container Runtime	Docker/containerd	Standard Kubernetes container runtimes

Dependencies

Helm Chart Dependencies

`postgresql` chart version 13.2.24 (Bitnami) — conditional on `postgresql.enabled`

Container Images

Airflow: `apache/airflow:3.1.7` (default)
StatsD Exporter: `quay.io/prometheus/statsd-exporter:v0.28.0`
Redis: `redis:7.2-bookworm` (limited to 7.2 due to licensing)
PgBouncer: `apache/airflow:airflow-pgbouncer-2025.03.05-1.23.1`
PgBouncer Exporter: `apache/airflow:airflow-pgbouncer-exporter-2025.03.05-0.18.0`
Git-Sync: `registry.k8s.io/git-sync/git-sync:v4.4.2`

Supported Kubernetes Versions

v1.30.13, v1.31.12, v1.32.8, v1.33.4, v1.34.0, v1.35.0

Credentials

`webserverSecretKeySecretName`: Kubernetes Secret containing Flask secret key for webserver session encryption.
`data.metadataConnection` or `data.metadataSecretName`: Database connection credentials.
`data.brokerUrl` or `data.brokerUrlSecretName`: Redis/Celery broker URL.
`registry.secretName`: Image pull secret for private container registries.
`dags.gitSync.sshKeySecret`: SSH key for git-sync DAG distribution.
`elasticsearch.secretName`: Elasticsearch connection for remote logging.

Quick Install

# Add the Airflow Helm repository
helm repo add apache-airflow https://airflow.apache.org
helm repo update

# Install Airflow on Kubernetes
helm install airflow apache-airflow/airflow \
  --namespace airflow \
  --create-namespace

# For local testing with kind
kind create cluster --image kindest/node:v1.30.13
helm install airflow apache-airflow/airflow --namespace airflow --create-namespace

Code Evidence

Chart API version from `chart/Chart.yaml:20-22`:

apiVersion: v2
name: airflow
version: 1.19.0
appVersion: 3.1.7

PostgreSQL dependency from `chart/Chart.yaml:35-39`:

dependencies:
  - name: postgresql
    version: 13.2.24
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled

Redis licensing constraint from `chart/values.yaml:113-115`:

  redis:
    repository: redis
    # Redis is limited to 7.2-bookworm due to licencing change
    # https://redis.io/blog/redis-adopts-dual-source-available-licensing/
    tag: 7.2-bookworm

Executor validation from `chart/values.schema.json:815-820`:

"executor": {
    "type": "string",
    "default": "CeleryExecutor",
    "pattern": "^(([a-zA-Z_][a-zA-Z0-9_]*.)*[A-Z][a-zA-Z0-9]+Executor)(,(...)*$"
}

Kubernetes version support from `dev/breeze/src/airflow_breeze/global_constants.py:154`:

ALLOWED_KUBERNETES_VERSIONS = ["v1.30.13", "v1.31.12", "v1.32.8", "v1.33.4", "v1.34.0", "v1.35.0"]

Common Errors

Error Message	Cause	Solution
`UPGRADE FAILED: chart requires kubeVersion >= 1.30`	Kubernetes cluster too old	Upgrade cluster to Kubernetes 1.30+
Pod `CrashLoopBackOff` on scheduler	Missing database connection	Configure `data.metadataConnection` in values.yaml
Redis connection refused	Redis not deployed or wrong URL	Verify `redis.enabled: true` or provide external `data.brokerUrl`
Git-sync failing	SSH key missing or wrong repo URL	Configure `dags.gitSync.sshKeySecret` with valid SSH key

Compatibility Notes

Redis 7.2: Pinned to 7.2-bookworm due to Redis adopting dual source-available licensing (SSPL + RSALv2) starting with Redis 7.4.
Executor Types: Supports CeleryExecutor, KubernetesExecutor, CeleryKubernetesExecutor, and LocalExecutor.
Token Expiration: Service account token expiration must be between 600 seconds (10 minutes) and 7,776,000 seconds (90 days).
Database Retention: Metadata database cleanup retention minimum is 1 day (default 90 days).
Helm Version: Chart tested with Helm v3.19.0 in CI.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment