Airflow Best Practices
11분 소요

Airflow의 공식 문서의 Best Practices를 번역 및 요약한 내용입니다.
Updated At: 2025–11–13: Apache Airflow 기반의 데이터 파이프라인에서 설명하는 Best Practices 내용 추가
‘Top-Level’ 코드 피하기
Airflow 스케줄러는 DAG 파일을 매우 자주 파싱(parsing)합니다. 이때, Python 함수의 내부가 아닌 파일 최상위 레벨(Top-Level)에 작성된 모든 코드가 매번 실행됩니다.
- Top-Level Code: Dag context 밖의 Code
import pendulum
from airflow.sdk import DAG
from airflow.sdk import task
import time
import pandas as pd # 1. 무거운 라이브러리를 최상위에 import
def expensive_api_call():
"""5초가 걸리는 무거운 작업 (예: API 호출, DB 조회)"""
print("API 호출 중...")
time.sleep(5)
return "API 결과"
my_expensive_response = expensive_api_call()
with DAG(
dag_id="bad_example_dag",
schedule=None,
start_date=pendulum.datetime(2023, 1, 1, tz="UTC"),
) as dag:
@task()
def print_expensive_api_call():
# 3. 이미 계산된 값을 사용
print(my_expensive_response)
멱등성(Idempotency): Task를 멱등하게 구현
Task는 “데이터베이스의 트랜잭션”처럼 다뤄야 합니다. 즉, Task는 여러 번 재시도(re-run)될 수 있으며, 몇 번을 실행하든 항상 동일한 결과를 보장해야 합니다. 이를 멱등성(Idempotency) 이라고 합니다.
“Task는 재현 가능하도록 설계해야 함”, 멱등하며 결정적이어야 함
중복 데이터 방지
INSERT대신UPSERT(UPDATE + INSERT)를 사용하세요.INSERT만 사용하면 재실행 시 데이터가 중복으로 쌓일 수 있음
특정 파티션 사용
“최신 데이터”를 읽는 것이 아닌 특정한 파티션 데이터를 읽어서 처리하도록 Task를 구현
재시도 사이에 원본 데이터가 변경되면 결과가 달라집니다. 대신 data_interval_start (Airflow 2.2+)나 execution_date (Airflow < 2.2) 같은 논리적 시간을 사용해 특정 데이터 파티션을 명시적으로 읽고 써야 합니다.
즉, 현재 시간(datetime.now())을 기준으로 로직을 처리하면 실행할 때마다 다른 결과를 만들 수 있기 때문에, 항상 DAG의 논리적 실행 시간을 사용해야 합니다.
단 Full Refresh(drop-create)되는 Task에서는 상관 없음
Task를 결정적으로 구현
결정적: 같은 input에 대해 항상 동일한 output을 반환 (FP의 순수함수와 같음)
- 비결정적인 동작:
- 함수 내 데이터 또는 데이터 구조의 암시적 순서에 의존 (dict 순서에 의존)
- 임의 값, 전역 변수, 디스크에 저장된 외부 데이터 등을 포함하여 외부 상태를 사용하는 경우
- 결과에 대한 명시적인 순서를 지정하지 않고 병렬로 데이터 처리를 수행
- 다중 스레드 코드 내에서 경쟁적 실행
- 부적절한 예외 처리
ex.) 데이터에 명시적 정렬을 적용하면 데이터 세트 순서에 대한 비결정성을 방지할 수 있음
변수(Variables) 및 Connections 사용
Airflow는 Variables 및 Connections 변수를 사용하여 DB conn과 변수를 동적으로 관리하고 사용할 수 있습니다.
Airflow Variables Variable.get("my_var") 역시 Top-Level 코드에서 사용하면 매번 DAG를 파싱할 때마다 Airflow DB에 네트워크 요청을 보냅니다.
from airflow.models import Variable
from airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator
# (X) DAG 파싱 시마다 DB 접근 발생 (Top Level)
SECRET_KEY = Variable.get("my_secret_key")
k8s_pod_op = KubernetesPodOperator(
task_id="bad_pod_example",
cmds=["echo", SECRET_KEY],
# ...
)
Jinja 템플릿 사용
Operator의 파라미터에 Jinja 템플릿(
{{ ... }})을 사용하면, Task가 실제 실행되는 시점에 변수 값을 가져옵니다. (lazy loading)
Task 내부에서 호출
PythonOperator의
python_callable함수 내부에서Variable.get()을 호출
from airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator
# (O) Jinja 템플릿을 사용하면 Task 실행 시점에 변수를 가져옴
k8s_pod_op = KubernetesPodOperator(
task_id="good_pod_example",
cmds=["echo", "{{ var.value.my_secret_key }}"],
# ...
)
Task 외부에서 호출
외부에서
Connection, Variable를 사용해야 한다면, Airflow DataStore에 저장 후 외부 시스템에서 연결 저장소(SQL) 등을 사용해 조회하는 방식으로 DRY 원칙을 지켜서 구현하는 것이 좋음
DRY: Don’t Repeat Yourself, 즉 중복을 피해서 변경을 최소화
Task 간 데이터 전달 (XCom vs. 원격 저장소)
Airflow는 XCom을 사용하여 Task 간의 데이터를 전달할 수 있습니다.
하지만 XCom은 DB에 JSON 형식으로 쓰이기 때문에 너무 큰 값을 처리할 때는 File_Path를 전달하는 방식으로 사용하는 게 좋습니다.
로컬 파일시스템 대신 원격 저장소 사용하기
Celery나 Kubernetes Executor 환경에서는 Task가 서로 다른 서버/컨테이너에서 실행됩니다. 한 Task가 로컬에 저장한 파일을 다음 Task가 읽을 수 없습니다.
원격 저장소(S3, HDFS 등)를 사용하는 게 좋습니다.
- 권장 패턴:
- Task A가 S3에 데이터를 처리/저장
- 저장된 S3 경로(
s3://...)를 XCom으로 push - Task B가 XCom에서 해당 경로를 pull하여 S3에서 데이터를 읽음
DAG 테스트 및 코드 품질
Dags를 프로덕션 수준 코드로 취급해야 하며, Dags에는 예상 결과를 생성하는지 확인하기 위한 다양한 관련 테스트(Unit Test, …)가 포함되어야 합니다.
DAG 로드 테스트
DAG 파일을 배포하기 전, 최소한 다음 명령으로 문법 오류나
import오류가 없는지 확인해야 합니다
$ python dags/my_dag_file.py
$ time dags/my_dag_file.py # 실행 시간을 확인할 수 있음
유닛 테스트
DagBag을 사용해 DAG가 정상적으로 로드되는지, 의도한 Task 수와 의존성(dependencies)을 가졌는지 테스트 코드를 작성할 수 있습니다
import glob
import os
import pytest
from airflow.models import DagBag
DAG_PATH = os.path.join(os.path.dirname(__file__), "../src/dags")
DAG_FILES = glob.glob(DAG_PATH, recursive=True)
@pytest.fixture
def dag_bag():
return DagBag(dag_folder=DAG_PATH, include_examples=False)
def test_dag_loaded(dag_bag):
assert dag_bag.import_errors == {}
- include_examples: 예제 DAG는 무시
Linting (코드 검사)
ruff같은 린터(Linter)와ruff-airflow플러그인을 사용해 Airflow에서 변경될 내용이나 비효율적인 패턴을 미리 감지하고 수정할 수 있습니다
Ruff — An extremely fast Python linter and code formatter, written in Rust.
$ pip install "ruff>=0.14.3"
$ ruff check dags/ --select AIR3
Airflow에서 일관된 스타일
DAG, Task 종속성을 정의할 때 일관된 스타일을 사용하는 것이 가독성 측면에서 좋음
ex.) with DAG() as dag 또는 dag = DAG() 중 하나의 일관된 스타일을 사용하자
Factory 함수를 사용하여 공통 패턴 사용하기
동일한 과정과 변환이 필요하여 많은 DAG에 걸쳐 반복 처리되는 공통적인 데이터 처리를 DAG 구조를 생성하는 Factory 함수를 사용하여 구현할 수 있음
# task_factory.py
def generate_tasks(
dataset_name, raw_dir, processed_dir, preprocess_script, output_dir, dag
) -> tuple[BaseOperator, BaseOperator]:
raw_path = os.path.join(raw_dir, dataset_name, "{ds_nodash}.json")
processed_path = os.path.join(processed_dir, dataset_name, "{ds_nodash}.json")
output_path = os.path.join(output_dir, dataset_name, "{ds_nodash}.json")
fetch_task = BashOperator(
task_id=f"fetch_{dataset_name}",
bash_command=f"echo 'curl http://example.com/{dataset_name}.json > {raw_path}.json'",
dag=dag,
)
preprocess_task = BashOperator(
task_id=f"preprocess_{dataset_name}",
bash_command=f"echo '{preprocess_script} {raw_path} {processed_path}'",
dag=dag,
)
export_task = BashOperator(
task_id=f"export_{dataset_name}",
bash_command=f"echo 'cp {processed_path} {output_path}'",
dag=dag,
)
fetch_task >> preprocess_task >> export_task
# Return first and last task 더 큰 그래프와 연결할 수 있도록 반환
return fetch_task, export_task
Data Quality 검사 (Self-Checks)
Task가 끝난 직후
S3KeySensor나SqlSensor등을 사용해 이전 Task의 산출물(파일, DB 데이터)이 정상적으로 생성되었는지 확인하는 단계를 추가하여 Data Quality를 검증해야 합니다.
‘Watcher Pattern’으로 DAG 실패 정확히 감지하기
데이터 처리 작업이 끝나면 항상 사용했던 리소스(임시 파일, 클러스터 등)를 정리하는
teardown(정리) Task를 실행하고 싶을 때가 있습니다. 이때trigger_rule=TriggerRule.ALL_DONE을 사용합니다. 이 룰은 “앞선 Task가 성공하든 실패하든 상관없이 무조건 실행하라” 는 뜻입니다.

- 문제점:
main_task가 실패했습니다.teardown_task(ALL_DONE)는 이 실패를 보고도 실행됩니다.teardown_task가 성공합니다.
결과: teardown_task가 DAG의 마지막 Task이므로, Airflow는 이 DAG Run 전체를 ‘성공(Success)’ 으로 처리합니다.
이 문제를 해결하기 위해 ‘감시자(Watcher)’ 역할을 하는 빈 Task를 추가합니다.
Watcher: 다른 Task가 하나라도 실패하면, 자신도 함께 실패하여 DAG 전체 상태를 ‘실패(Failed)‘로 만듭니다. trigger_rule을 TriggerRule.ONE_FAILED로 설정합니다. (앞선 Task 중 하나라도 실패하면 실행)
충돌하거나 복잡한 Python 종속성 처리
Airflow에는 많은 Python 종속성이 있기 때문에 때때로 Airflow 종속성이 작업 코드에서 예상하는 종속성과 충돌하는 경우가 있습니다.
기본적으로 Airflow 환경은 단일 Python 종속성 집합과 단일 Python 환경으로 구성되므로, 일부 작업이 다른 작업과 다른 종속성을 필요로 하고 이러한 종속성이 기본적으로 작업 간에 충돌하는 경우가 종종 발생할 수 있습니다.
일반적으로 Airflow는 orchestration 도구로만 사용될 때 더 효율적입니다. 데이터에 대한 처리는 외부 시스템(Spark, …)으로 분리하는 것이 좋습니다.
PythonVirtualenvOperator 사용하기
PythonVirtualenvOperator(or
@task.virtualenv)를 사용하면 Python 호출 가능 함수가 실행될 가상 환경을 동적으로 생성할 수 있습니다
- 사용자 환경에 따라 가상 환경 생성
- Python 호출 가능 항목을 직렬화하고 virtualenv Python 인터프리터로 실행에 전달합니다.
- 이를 실행하고 호출 가능한 결과를 검색하고 지정된 경우 xcom을 통해 푸시합니다.
ExternalPythonOperator 사용하기
버전 2.4에 추가되었으며, 좀 더 복잡하지만 오버헤드, 보안, 안정성 문제가 훨씬 적은 방법입니다. (
@task.external_python)
가상 환경을 만드는 방식이 아닌 외부 가상환경에서 Task가 동작하는 방식으로, 이렇게 하면 가상 환경을 다시 만드는 데 따르는 오버헤드와 문제를 피할 수 있지만, Airflow 설치와 함께 준비하고 배포해야 합니다.
@task.external_python(task_id="external_python", python=PATH_TO_PYTHON_BINARY)
def callable_external_python():
"""
Example function that will be performed in a virtual environment.
Importing at the module level ensures that it will not attempt to import the
library before it is installed.
"""
import sys
from time import sleep
print(f"Running task via {sys.executable}")
print("Sleeping")
for _ in range(4):
print("Please wait...", flush=True)
sleep(1)
print("Finished")
external_python_task = callable_external_python()
DockerOperator / KubernetesPodOperator
특정 실행해야 하는 대상 스크립트를 Docker Image로 관리하고 DockerOperator를 사용하여 Airflow에서 Container 형태로 실행할 수 있습니다.
# Dockerfile
FROM python:3.8-slim
RUN python -m pip install click==7.1.1 requests==2.23.0
COPY scripts/fetch_ratings.py /usr/local/bin/fetch-ratings
RUN chmod +x /usr/local/bin/fetch-ratings
# 컨테이너 내에서 fetch-ratings 명령어를 사용할 수 있도록 PATH 설정
ENV PATH="/usr/local/bin:${PATH}"
# dag
...
fetch_ratings = DockerOperator(
task_id="fetch_ratings",
image="manning-airflow/movielens-fetch",
auto_remove="force",
mount_tmp_dir=False,
command=[
"fetch-ratings",
"--start_date",
"{{ds}}",
"--end_date",
"{{next_ds}}",
"--output_path",
"/data/ratings/{{ds}}.json",
"--user",
"airflow",
"--password",
"airflow",
"--host",
"http://host.docker.internal:5001",
],
network_mode="airflow",
mounts=[
Mount(
source="/tmp/airflow/data", # 호스트 경로
target="/data", # 컨테이너 경로
type="bind", # 바인딩 마운트 타입 지정
)
],
)
...
Task를 삭제할 때 주의사항
운영 중인 DAG에서 더 이상 필요 없는 Task(예:
old_task)를 DAG 파일에서 단순히 삭제(또는 주석 처리)하면, UI에서old_task가 사라지며 그 Task의 모든 과거 실행 기록(로그, 상태, 이력)에 접근할 방법이 UI 상에서 사라집니다
과거 실행 이력을 보존하는 것이 중요하다면, Task를 삭제하는 대신 DAG를 새로 ‘버전업’ 하는 방법을 선택
- 기존 DAG(
my_dag_v1) 코드를 복사하여my_dag_v2라는 새 DAG 파일(새dag_id)을 만듭니다. my_dag_v2에서 원하는 Task를 삭제하거나 로직을 수정합니다.- 기존
my_dag_v1을 ‘Pause(일시 중지)’ 상태로 변경합니다. - 새로운
my_dag_v2를 ‘Active(활성)’ 상태로 배포합니다.
이렇게 하면, 과거 이력은 my_dag_v1에서 언제든 조회할 수 있고, 새로운 로직은 my_dag_v2가 처리하게 되어 이력과 안정성을 모두 지킬 수 있습니다.
효율적인 데이터 처리
원하는 결과를 얻기 위해 최소한의 데이터로 처리를 제한하는 것이 좋습니다.
데이터 처리량 제한하기
특정 사용자와 주문 정보를 저장하는 pipeline을 구현할 때
Join 후 테이블을 대상으로 하면 특정 사용자 외에 불필요한 데이터가 로드됩니다.
- filter:
… from user where user_id in () - join:
user_t join order_t on user_t.id = order_t.user_id
중간 단계 데이터 캐싱
pipeline을 구성 시 각 Task는 다운스트림에 데이터를 전달해주는 경우가 많습니다. 이 경우 실패한 다운스트림만을 다시 실행할 수 있도록 중간 단계를 파일(S3, …) 또는 Database or XCom으로 캐싱하는 것이 좋습니다.
자원관리
대용량 데이터를 가지고 작업할 때, 데이터 처리에 사용되는 Airflow 클러스터나 다른 시스템의 한도를 넘는 경우가 있습니다.
많은 태스크를 병렬로 실행할 때 Pool을 사용하기
Airflow는
max_active_runs, max_active_tasks등을 사용하여 Airflow 내에서 동시성을 제어할 수 있습니다.
Spark 또는 외부 시스템에 대한 접근을 제한(pool)을 통해서 다른 시스템의 한도를 넘지 않도록 제한할 수 있습니다.
PythonOperator(
task_id="my_task",
python_callable=my_function,
pool="spark_pool", # 'web UI를 통해서 정의할 수 있음
)
SLA 및 경고를 사용하여 장기 실행 작업 탐지
태스크나 DAG의 실행이 평소보다 오래 걸릴 수 있으며 이러한 상황을 탐지하기 위해 SLA(서비스 수준 계약)를 설정하고, SLA 위반 시 경고를 받을 수 있습니다.
default_args = {
"sla": timedelta(minutes=30), # 태스크가 30분 이상 실행되면 SLA 위반으로 간주
}
with DAG(
dag_id="my_dag",
default_args=default_args,
"sla_miss_callback": my_sla_miss_callback, # SLA 위반 시 호출할 콜백 함수
schedule_interval = "@daily",
) as dag:
...
Airflow 메타데이터 DB 유지보수
Airflow는 모든 DAG 실행 이력, Task 실행 상태, 로그, XCom 값 등을 중앙 메타데이터 DB에 저장합니다. 1년, 2년 운영하다 보면 이 데이터는 수십 GB, 수백 GB까지 거대해질 수 있으며 이는 Airflow의 성능 저하로 이어집니다.
airflow db clean CLI
Airflow는 오래된 실행 기록을 정리할 수 있는 내장 CLI 명령어를 제공합니다
이 명령어는 데이터를 영구적으로 삭제하며, 프로덕션 환경에서 실행하기 전 DB 백업(스냅샷)을 수행하고, --dry-run 옵션으로 먼저 테스트해야 합니다.
1단계: Dry Run (시뮬레이션)
먼저
--dry-run플래그를 붙여서, 실제로 삭제하지 않고 “어떤 테이블에서 몇 개의 행이 삭제될 것인지” 만 확인합니다.
# 90일보다 오래된 dag_run, task_instance, log, task_fail 기록을
# 실제로 지우지 않고 몇 개나 지워질지 확인만 함
$ airflow db clean \
--tables dag_run task_instance log task_fail \
--clean-before-days 90 \
--dry-run
2단계: 실제 실행
--dry-run의 결과를 보고 “이만큼 삭제해도 되겠다”라고 판단이 서면, DB를 백업한 후--dry-run플래그만 빼고 실행합니다. (필요에 따라--skip-archiving을 추가하여 백업 파일 생성을 건너뛸 수 있습니다.)
$ airflow db clean \
--tables dag_run task_instance log task_fail \
--clean-before-days 90