Airflow 해부 (2) 설치와 첫 실행: constraint와 standalone

Airflow 해부 시리즈의 2편입니다. 전체 목차는 0편에 있습니다.

constraint 파일이 필수인 이유

Airflow는 의존 패키지가 수백 개 수준으로 많습니다. 그래서 Airflow 프로젝트는 버전과 Python 버전 조합마다 “이 의존성 버전 조합은 함께 동작한다”를 검증한 constraint 파일을 배포하고, 설치는 반드시 이 파일과 함께 합니다.

AIRFLOW_VERSION=3.0.2
PYTHON_VERSION=3.12
pip install "apache-airflow==${AIRFLOW_VERSION}" \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"

constraint 없이 pip install apache-airflow만 실행하는 것이 설치 단계의 대표 사고입니다. 설치는 성공하는데 어긋난 의존성 버전 때문에 나중에 import 에러가 나고, 원인이 설치 방식이라는 것을 알기까지 오래 걸립니다.

프로젝트 가상환경에 직접 설치하는 것은 학습 단계까지만 권합니다. 프로젝트의 다른 패키지와 충돌하기 쉬워서, 운영은 6편처럼 컨테이너로 분리합니다.

standalone으로 첫 구동

airflow standalone

이 명령 하나가 개발용 구성을 전부 만듭니다.

1. ~/airflow/에 홈 디렉토리와 설정 파일(airflow.cfg) 생성
2. SQLite metadata DB 초기화
3. 관리자 계정 생성 (비밀번호가 터미널에 출력됩니다)
4. scheduler와 web UI 실행

http://localhost:8080 에 접속해 출력된 계정으로 로그인하면 예제 DAG 목록이 보입니다. standalone은 어디까지나 로컬 학습용이고, 프로세스를 끄면 전부 내려갑니다.

첫 실행 동선

UI에서 예제 DAG 하나로 기본 동선을 익힙니다.

1. DAG 목록에서 example_bash_operator 같은 예제를 찾고, 왼쪽 토글로 활성화합니다. DAG는 활성화 전까지 스케줄이 돌지 않습니다
2. 오른쪽의 Trigger 버튼으로 수동 실행합니다
3. Grid view에서 방금 생긴 열의 칸(task instance)들이 초록색으로 바뀌는 것을 확인합니다
4. 칸 하나를 눌러 Logs 탭에서 실행 로그를 봅니다

이 네 단계(활성화, 트리거, 상태 확인, 로그)가 Airflow 사용의 최소 루프입니다. 실패한 task를 다시 돌리는 것도 같은 화면에서 Clear 버튼으로 합니다. Clear는 “상태를 지워서 scheduler가 다시 돌리게 만든다”는 의미라서, 이름과 달리 재실행 버튼에 해당합니다.

내 DAG를 두는 곳

직접 만든 DAG 파일은 ~/airflow/dags/ 아래에 둡니다. scheduler가 이 폴더를 주기적으로 스캔하므로 별도 등록 절차는 없지만, 새 파일이 UI에 나타나기까지 수십 초의 파싱 지연이 있습니다. 파일을 넣었는데 안 보인다면 먼저 문법 에러를 의심하고 다음 명령으로 확인합니다.

python ~/airflow/dags/my_dag.py   # import 에러가 있으면 여기서 드러난다

예제 DAG가 목록에 많아 거슬리면 airflow.cfg에서 load_examples = False로 끕니다.

다음 편에서 DAG를 직접 작성합니다.

다음 글: Airflow 해부 (3) DAG 작성 기초: TaskFlow API와 의존성