공식 Helm 차트 1.22.0[1] 으로 Airflow 3.x 를 Kubernetes 에 올린다. KubernetesExecutor 를 쓰고 DAG 는 git-sync 로 받는다.
| 항목 | 요구[1:1] |
|---|---|
| Kubernetes | 1.30.13 이상 |
| Helm | 3.19.0 이상 |
| Airflow | 2.11 이상 · 3.0 이상 |
| 스토리지 | 메타데이터 DB · 로그용 PVC 를 만들 StorageClass |
차트에 번들된 PostgreSQL 은 시험용이다. 운영은 외부 PostgreSQL 을 둔다[2].
helm repo add apache-airflow https://airflow.apache.org
helm repo update
helm search repo apache-airflow/airflow # CHART VERSION 1.22.0
kubectl create namespace airflow
# 외부 DB 연결 문자열
kubectl -n airflow create secret generic airflow-metadata \
--from-literal=connection=postgresql://airflow:${AIRFLOW_DB_PASSWORD}@db01.example.com:5432/airflow
# API 서버 세션 키 · JWT 시크릿 · fernet 키
kubectl -n airflow create secret generic airflow-api-secret \
--from-literal=api-secret-key="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
kubectl -n airflow create secret generic airflow-jwt-secret \
--from-literal=jwt-secret="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
kubectl -n airflow create secret generic airflow-fernet \
--from-literal=fernet-key="$(python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
# DAG 저장소 읽기용 SSH 키 (deploy key)
ssh-keygen -t ed25519 -N '' -f ./airflow-dags-deploy-key
kubectl -n airflow create secret generic airflow-ssh-secret \
--from-file=gitSshKey=./airflow-dags-deploy-key
airflowVersion: "3.3.2"
defaultAirflowTag: "3.3.2"
executor: KubernetesExecutor
# 외부 메타데이터 DB
postgresql:
enabled: false
data:
metadataSecretName: airflow-metadata
# 시크릿 (3.x 는 webserverSecretKey 가 아니라 apiSecretKey)
apiSecretKeySecretName: airflow-api-secret
jwtSecretName: airflow-jwt-secret
fernetKeySecretName: airflow-fernet
# DAG — git-sync
dags:
gitSync:
enabled: true
repo: git@git.example.com:team/airflow-dags.git
branch: main
subPath: "dags"
sshKeySecret: airflow-ssh-secret
# knownHosts 를 주지 않으면 호스트 키 검사를 건너뛴다. 운영에서는 넣는다.
knownHosts: |
git.example.com ssh-ed25519 AAAA...
# 로그 — 파드가 사라져도 남게 PVC 로
logs:
persistence:
enabled: true
size: 20Gi
storageClassName: standard
# 3.x 에서는 webserver 블록이 아니라 apiServer 블록이다
apiServer:
service:
type: ClusterIP
replicas: 1
dagProcessor:
enabled: true
triggerer:
enabled: true
# 사설 레지스트리를 쓰면
# images:
# airflow:
# repository: registry.example.com/library/apache/airflow
# tag: "3.3.2"
Airflow 3 에서는 차트의 webserver.* 항목이 전부 apiServer.* 로 바뀌었다[3]. 2.x 용 values 를 그대로 쓰면 값이 무시된다.
helm upgrade --install airflow apache-airflow/airflow \
--namespace airflow --create-namespace \
--version 1.22.0 \
-f values.yaml
kubectl -n airflow get pods
# airflow-api-server-... 1/1 Running
# airflow-scheduler-... 2/2 Running
# airflow-dag-processor-... 2/2 Running
# airflow-triggerer-... 2/2 Running
# airflow-statsd-... 1/1 Running
scheduler · dag-processor 파드의 두 번째 컨테이너가 git-sync 사이드카다. kubectl -n airflow logs deploy/airflow-dag-processor -c git-sync 로 저장소를 받았는지 본다.
kubectl -n airflow port-forward svc/airflow-api-server 8080:8080
http://localhost:8080/. 기본 인증 관리자(Simple Auth Manager)의 admin 비밀번호는 api-server 파드 로그 또는 파드 안의 simple_auth_manager_passwords.json.generated 에 있다.
kubectl -n airflow exec deploy/airflow-api-server -- cat /opt/airflow/simple_auth_manager_passwords.json.generated
외부 노출은 ingress.apiServer.enabled: true 로 Ingress 를 만들거나 apiServer.service.type: NodePort 로 한다.
kubectl -n airflow exec deploy/airflow-scheduler -c scheduler -- airflow dags list
kubectl -n airflow exec deploy/airflow-scheduler -c scheduler -- airflow dags trigger <dag_id>
kubectl -n airflow get pods -w # KubernetesExecutor 는 태스크마다 파드를 띄운다
kubectl -n airflow get events --sort-by=.lastTimestamp | tail
helm repo update
helm upgrade airflow apache-airflow/airflow --namespace airflow --version <새 차트 버전> -f values.yaml
helm uninstall airflow --namespace airflow # PVC 는 남는다
차트 업그레이드 전에 helm show values apache-airflow/airflow --version <버전> 으로 키가 바뀌지 않았는지 본다.
Helm Chart 1.22.0 — 2026-09-20 확인. https://airflow.apache.org/docs/helm-chart/stable/index.html ↩︎ ↩︎
Production Guide — 2026-09-20 확인. https://airflow.apache.org/docs/helm-chart/stable/production-guide.html · Manage DAG files: https://airflow.apache.org/docs/helm-chart/stable/manage-dag-files.html ↩︎
Upgrading to Airflow 3 — 2026-09-20 확인. https://airflow.apache.org/docs/apache-airflow/stable/installation/upgrading_to_airflow3.html ↩︎