Airflow

설치 준비: Python 버전과 AIRFLOW_HOME

Airflow를 설치하려면 Python 3 환경이 필요하다. Airflow 3.2.0부터는 Python 3.10, 3.11, 3.12, 3.13, 3.14를 공식 지원한다. 공식적으로 지원되는 설치 방법은 ``pip``와 ``uv`` 두 가지이며, ``uv``는 훨씬 빠른 대안으로 가상환경(venv) 생성도 자동으로 처리해준다. ``poetry``나 ``pip-tools``도 성공 사례가 있지만 constraint 파일과 요구사항(requirements) 관리 워크플로우가 pip/uv와 다르기 때문에 공식 지원 대상은 아니다 — 이런 도구를 쓰고 싶다면 constraint 파일을 해당 도구의 형식/워크플로우에 맞게 직접 변환해야 한다. Windows에서는 WSL2(``wsl --install``)가 필요하다.

Airflow는 홈 디렉터리가 필요하며 기본값은 ``~/airflow``이지만, ``AIRFLOW_HOME`` 환경변수로 원하는 위치를 지정할 수 있다. 이 환경변수는 설치 과정보다 먼저 설정해야 한다 — 설치 과정이 필요한 파일을 어디에 저장할지 미리 알아야 하기 때문이다.

constraint 파일로 재현 가능하게 설치하기

Airflow는 ``pip install apache-airflow[EXTRAS]==AIRFLOW_VERSION --constraint "<constraint URL>"`` 형태의 명령으로 설치하는 것을 권장한다. 예를 들어 ``pip install "apache-airflow[celery]==3.0.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.10.txt"``처럼, 사용할 Airflow 버전과 Python 버전 조합에 맞는 constraint 파일 URL을 함께 지정한다. constraint URL은 ``https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt`` 패턴을 따르므로, 셸에서 Python 버전을 추출해 URL을 조립할 수도 있다.

이렇게 constraint 파일을 명시하는 이유는 의존성 버전을 고정해 설치 결과가 재현 가능하도록 만들기 위해서다. ``uv``를 쓰면 같은 옵션으로 ``uv pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"``처럼 더 빠르게 설치할 수 있다. Debian/Ubuntu 계열에서는 PEP 668(externally managed environment)로 인해 시스템 전역에 pip install이 막힐 수 있으므로, ``python3 -m venv``로 가상환경을 만들고 그 안에서 활성화한 뒤 설치하는 것이 안전하다.

airflow standalone으로 한 번에 띄우기

``airflow standalone`` 명령은 데이터베이스를 초기화하고, 관리자 사용자를 생성하고, 필요한 모든 컴포넌트를 한 번에 시작해준다. Airflow 3.x부터는 관리자 비밀번호가 터미널 출력에 항상 표시되지는 않을 수 있는데, 이 경우 비밀번호는 ``$AIRFLOW_HOME/simple_auth_manager_passwords.json.generated`` 파일에 자동 생성되어 저장되므로 ``cat ~/airflow/simple_auth_manager_passwords.json.generated``로 확인할 수 있다.

설치가 끝나면 브라우저에서 ``localhost:8080``에 접속해 터미널에 표시된(또는 위 파일에서 확인한) 관리자 계정으로 로그인한다. 홈 화면에서 ``example_bash_operator`` Dag을 활성화(enable)하면 바로 동작을 확인해볼 수 있다.

이 명령을 실행하면 ``$AIRFLOW_HOME`` 폴더와, 기본값이 채워진 ``airflow.cfg`` 파일이 생성된다. 이 기본값은 환경변수로 오버라이드할 수 있고, ``$AIRFLOW_HOME/airflow.cfg`` 파일을 직접 열어보거나 UI의 Admin → Configuration 메뉴에서도 확인할 수 있다. 웹서버의 PID 파일은 ``$AIRFLOW_HOME/airflow-api-server.pid``(또는 systemd로 시작한 경우 ``/run/airflow/airflow-webserver.pid``)에 저장된다.

프로덕션을 향해: 컴포넌트를 개별적으로 실행하기

규모가 커지고 프로덕션으로 갈수록, 여기서 사용한 ``standalone`` 명령에서 벗어나 컴포넌트들을 각각 별도로 실행하게 된다. ``standalone``이 한 번에 처리해주던 작업을 풀어서 보면 다음과 같다.

airflow db migrate

airflow users create \
    --username admin \
    --firstname Peter \
    --lastname Parker \
    --role Admin \
    --email spiderman@superhero.org

airflow api-server --port 8080

airflow scheduler

airflow dag-processor

airflow triggerer

``airflow db migrate``는 메타데이터 데이터베이스의 테이블을 초기화·마이그레이션한다. ``airflow users create``는 관리자 계정을 만드는데, 이 명령은 FAB(Flask-AppBuilder) 인증 매니저 프로바이더가 활성화된 경우에만 사용할 수 있다. 나머지 네 개는 각자 독립적으로 동작하는 장기 실행 프로세스다 — ``api-server``는 웹 UI와 REST API를 서빙하고, ``scheduler``는 Dag의 스케줄을 판단해 태스크를 큐에 올리며, ``dag-processor``는 Dag 정의 파일을 주기적으로 파싱해 최신 상태로 유지하고, ``triggerer``는 비동기로 지연(defer)된 태스크를 관리한다. 이렇게 컴포넌트를 분리하면 각 컴포넌트를 독립적으로 스케일링하거나 재시작할 수 있다.

첫 태스크 인스턴스와 백필 실행해보기

몇 가지 명령으로 실제 태스크 인스턴스를 실행해볼 수 있다.

# 첫 번째 태스크 인스턴스 실행
airflow tasks test example_bash_operator runme_0 2015-01-01
# 이틀치 백필 실행
airflow backfill create --dag-id example_bash_operator \
    --from-date 2015-01-01 \
    --to-date 2015-01-02

이 명령들을 실행하면 ``example_bash_operator`` Dag에서 작업 상태가 바뀌는 것을 UI에서 확인할 수 있다. ``airflow tasks test``는 특정 태스크 인스턴스 하나를 로컬에서 즉석으로 실행해 로그를 즉시 확인하는 용도이고, ``airflow backfill create``는 지정한 날짜 범위 전체에 대해 정식 Dag 실행을 생성해 과거 데이터를 처리하는 용도다.