DAG writing best practices in Apache Airflow
Source: astronomer.io/docs Type: article (공식 문서) By: Astronomer Valid as of: 2026-04-25
Key Insight
Airflow DAG 설계의 핵심은 멱등성(Idempotency). 재실행해도 동일한 결과를 보장하도록 태스크를 원자적으로 설계하고, top-level 코드를 제거하며, Jinja 템플릿으로 시점 의존성을 없애는 것이 기본 원칙이다.
핵심 Takeaway
- DAG 멱등성: 동일 입력으로 몇 번 실행해도 동일한 결과 → Retry와 장애복구의 기반 (출처: 본문 “Review idempotency”)
- 태스크 원자화: ETL을 Extract·Transform·Load 3개 태스크로 분리 → 독립 재실행 가능
- Top-level 코드 회피: Scheduler가 30초마다 DAG 파싱 → 파싱 시점에 외부 시스템 호출 금지
- Jinja 템플릿 사용:
datetime.today()대신{{ prev_start_date_success }}→ 시점 고정으로 멱등성 확보 - 증분 처리: DAG 실행 구간의 레코드만 처리 (last_modified_date 또는 sequence_id 기준)
상세 요약
멱등성과 Retry
멱등성이 확보된 DAG는 동일 DAG Run을 여러 번 실행해도 데이터 중복·손실이 없다. 이를 기반으로 Airflow의 Retry 기능이 안전하게 작동한다. Retry는 Task → DAG default_args → 환경변수 AIRFLOW__CORE__DEFAULT_TASK_RETRIES 순으로 우선순위가 적용되며, retries=2가 분산 환경 대부분의 문제를 커버한다.
DAG 설계 원칙
태스크를 원자적으로 유지하면 파이프라인 일부 실패가 전체에 영향을 주지 않는다. Top-level 코드(DAG 파싱 시 실행되는 코드)는 Scheduler 부하를 유발하고 멱등성을 깨뜨리므로, 외부 시스템 연결은 반드시 Task 내부에 감싸야 한다.
증분 처리 패턴
전체 데이터셋 대신 실행 구간(hour/day)의 레코드만 처리하면 특정 구간 실패 시 해당 구간만 재실행하면 된다. last_modified_date 기반이 권장되며, 불가능하면 sequence ID를 사용한다.
환경 구성
Provider packages로 서드파티 통합을 직접 구현하지 않아도 된다. 대용량 데이터 처리는 Airflow 내부보다 Apache Spark 등에 위임하고, KubernetesExecutor로 태스크별 리소스를 제어한다.
연결되는 위키 페이지
- dag-idempotency — 멱등성 개념 상세
- airflow-dag-design-patterns — DAG 설계 패턴 모음
- apache-airflow — Apache Airflow 엔티티