Apache Airflow란 무엇인가?

Apache Airflow는 워크플로 (workflows)를 프로그래밍 방식으로 작성, 스케줄링 및 모니터링하는 데 사용되는 오픈 소스 플랫폼입니다. 데이터 엔지니어링 (data engineering), MLOps, 그리고 백엔드 자동화 파이프라인에서 널리 사용됩니다. ETL 파이프라인을 구축하거나, 예약된 작업을 실행하거나, 복잡한 워크플로를 오케스트레이션 (orchestrating)하고 있다면 Airflow는 당신이 접하게 될 도구일 것입니다.

Airflow 3는 Airflow 2에서 대폭 업그레이드된 버전입니다. 새로운 React 기반의 UI, 전용 API 서버 (기존의 webserver를 대체), Task SDK를 통한 개선된 작업 격리 (task isolation), 그리고 전반적으로 향상된 확장성 (scalability)을 도입했습니다.

사전 요구 사항

시작하기 전에 다음 사항들이 준비되었는지 확인하세요:

1. Windows Subsystem for Linux (WSL2) 설치 완료

Windows 머신에 **Ubuntu 24.04 (Noble)**가 설치된 WSL 2가 필요합니다. 아직 설정하지 않았다면, PowerShell을 관리자 권한으로 열고 다음을 실행하세요:

wsl --install

안내 메시지가 뜨면 머신을 재시작한 다음, 시작 메뉴에서 Ubuntu를 실행하세요.

중요: 항상 /mnt/c/...와 같은 Windows 마운트 경로가 아닌, Linux 홈 디렉토리(~) 내에서 작업하세요. 마운트된 드라이브에서는 성능 및 파일 권한 문제가 발생할 수 있습니다.

2. MobiXterm 또는 Windows Terminal (선택 사항이지만 권장)

둘 중 하나를 사용하면 WSL 내부에서 작업할 때 더 나은 터미널 경험을 제공합니다.

3. Linux 터미널에 대한 기본적인 익숙함

Linux 전문가일 필요는 없지만, 디렉토리를 탐색(cd, ls)하고 명령어를 실행하는 방법을 알고 있으면 도움이 됩니다.

1단계: 시스템 업데이트

WSL 터미널을 열고 다음을 실행하세요:

sudo apt update && sudo apt upgrade -y

이를 통해 패키지 목록과 설치된 패키지를 최신 상태로 유지할 수 있습니다.

2단계: Python 3 설치 및 버전 확인

Ubuntu 24.04에는 기본적으로 Python 3.12가 포함되어 있습니다. 사용 가능한지 확인하세요:

python3 --version

Python 3.12.x와 같은 메시지가 보여야 합니다. Airflow 3.1.3은 Python 3.10, 3.11, 3.12를 지원하므로 준비가 된 상태입니다.

만약 Python이 설치되어 있지 않다면:

sudo apt install python3 python3-dev python3-pip python3-venv -y

Step 3: AIRFLOW_HOME 설정하기 (중요 — 가장 먼저 수행하세요)

Airflow는 설정(configuration), 로그(logs), 데이터베이스(database)를 저장하기 위한 홈 디렉터리가 필요합니다. Airflow를 설치하기 전에 이를 설정하여 모든 데이터를 어디에 저장할지 지정해야 합니다:

export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home

터미널을 재시작해도 설정이 유지되도록 영구적으로 적용하려면:

echo 'export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home' >> ~/.bashrc
source ~/.bashrc

이 단계가 중요한 이유: 이 단계를 건너뛰면 Airflow는 기본값인 ~/airflow를 사용하게 되며, 이전 Airflow 설치에서 사용하던 설정 파일을 불러와 예상치 못한 경고나 오류를 발생시킬 수 있습니다.

Step 4: 프로젝트 디렉터리 및 가상 환경(Virtual Environment) 생성

Airflow 3.1.3 설치를 위한 전용 폴더를 생성합니다:

mkdir ~/airflow-3.1.3
cd ~/airflow-3.1.3

폴더 내부에 가상 환경 (virtual environment)을 생성합니다:

python3 -m venv env

가상 환경을 활성화합니다:

source env/bin/activate

이제 터미널 프롬프트 시작 부분에 (env)가 표시되어야 합니다:

(env) user@DESKTOP-XXXX:~/airflow-3.1.3$

Step 5: pip 업그레이드

Airflow를 설치하기 전에 pip를 최신 버전으로 업그레이드합니다:

pip install --upgrade pip

Step 6: 제약 사항(Constraints)을 사용하여 Apache Airflow 3.1.3 설치

공식 제약 사항(constraints) 파일을 사용하여 Airflow를 설치합니다. 이는 매우 중요합니다. Airflow는 많은 의존성(dependencies)을 가지고 있으며, 제약 사항 파일은 충돌 없이 호환 가능한 버전들이 함께 설치되도록 보장합니다:

pip install "apache-airflow==3.1.3" \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

이 작업은 몇 분 정도 걸릴 수 있습니다. 완료되면 설치를 확인합니다:

airflow version

다음과 같이 출력되어야 합니다:

3.1.3

Step 7: FAB Auth Manager Provider 설치

Airflow 3에서는 사용자 인증(user authentication)이 별도의 프로바이더(provider) 패키지에 의해 처리됩니다. 지금 이를 설치하세요. 설치하지 않으면 API 서버가 시작되지 않습니다:

pip install apache-airflow-providers-fab \-
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

참고: airflow users 명령은 FAB (Flask AppBuilder) 인증 매니저 (auth manager) 프로바이더가 설치되어 있을 때만 사용할 수 있습니다. 이는 사용자 관리 기능이 코어 (core)에 내장되어 있었던 Airflow 2와의 주요 차이점입니다.

8단계: Airflow 데이터베이스 초기화

Airflow 3는 기존의 db init 명령 대신 db migrate를 사용합니다. 이 명령은 메타데이터 데이터베이스 (metadata database)를 생성하고 모든 스키마 마이그레이션 (schema migrations)을 적용합니다:

airflow db migrate

9단계: 관리자 사용자 생성

airflow users create \-
  --username admin \-
  --firstname YourFirstName \-
...

비밀번호를 설정하라는 메시지가 표시됩니다. 주의해서 입력하세요. 터미널에서는 입력 내용이 숨겨집니다 (별표 *도 표시되지 않음). 확인 메시지가 뜨면 다시 한번 입력하세요.

팁: 이 비밀번호를 기억해 두세요. 평문 (plain-text)으로 저장된 복사본은 어디에도 없습니다. 비밀번호를 잊어버렸다면 airflow users reset-password --username admin 명령으로 재설정할 수 있습니다.

10단계: Airflow API 서버 및 스케줄러 시작

Airflow 3는 세 가지 프로세스가 동시에 실행되어야 합니다 — API 서버 (API server), 스케줄러 (scheduler), 그리고 선택적으로 (더 큰 규모의 설정의 경우) dag-processor입니다. 각 프로세스를 위해 별도의 WSL 터미널 탭이나 창을 여세요.

터미널 1 — API 서버 시작:

cd ~/airflow-3.1.3
source env/bin/activate
export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home
...

터미널 2 — 스케줄러 시작:

cd ~/airflow-3.1.3
source env/bin/activate
export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home
...

참고: Airflow 3에서는 airflow webserver가 airflow api-server로 대체되었습니다. 이는 Airflow 2에서 이루어진 주요 아키텍처 (architectural) 변경 사항 중 하나입니다.

API 서버가 성공적으로 시작되면 다음과 같은 메시지가 표시됩니다:

INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

그리고 스케줄러가 시작되면 다음과 같은 메시지가 표시됩니다:

INFO:     Starting the scheduler
INFO:     Loaded executor: LocalExecutor

11단계: Airflow UI 접속하기

브라우저를 열고 다음 주소로 이동하세요:

새로운 Airflow 3 React 기반 로그인 페이지가 나타납니다. 9단계에서 생성한 사용자 이름(username)과 비밀번호(password)를 입력하세요.

이제 **Airflow 3 대시보드 (Dashboard)**에 접속되었습니다. 이제 DAG를 생성하고 관리할 준비가 되었습니다!

빠른 참조: 재부팅 후 Airflow 시작하기

컴퓨터를 재시작한 후 Airflow를 사용하려면, 매번 별도의 터미널에서 다음 명령어들을 실행해야 합니다:

# 모든 터미널: 디렉토리 이동, 가상 환경(venv) 활성화, 그리고 AIRFLOW_HOME 설정
cd ~/airflow-3.1.3
source env/bin/activate
...

만약 3단계에서 ~/.bashrc에 AIRFLOW_HOME을 추가했다면, export 과정은 자동으로 수행되므로 해당 라인은 건너뛰어도 됩니다.

Airflow 3 vs Airflow 2 — 주요 차이점

Airflow 2에 익숙하시다면, 다음과 같은 변경 사항이 있습니다:

Airflow 2.x	Airflow 3.x
airflow webserver	airflow api-server
...

문제 해결 (Troubleshooting)

airflow users 명령어를 찾을 수 없음 (command not found)

FAB 프로바이더 (FAB provider)를 설치하세요:

pip install apache-airflow-providers-fab \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

[webserver] 설정에 대한 Deprecation warnings (지원 중단 경고)

이 경고는 Airflow 3가 이전 Airflow 2 설치 환경의 설정 파일을 불러올 때 발생합니다. AIRFLOW_HOME이 ~/airflow(Airflow 2의 기본값)가 아닌 새로운 디렉토리를 가리키고 있는지 확인하세요.

No module named 'airflow.providers.fab' 경고

FAB 프로바이더가 설치되지 않았습니다. 위의 7단계를 참조하세요.

관리자(admin) 비밀번호를 잊어버린 경우

사용자를 삭제하지 않고 비밀번호를 재설정하세요:

airflow users reset-password --username admin

포트 8080이 이미 사용 중인 경우 (Port 8080 already in use)

8080 포트를 사용 중인 다른 프로세스를 중지하거나, API 서버를 다른 포트에서 시작하세요:

airflow api-server --port 8081

모든 명령어 요약

# AIRFLOW_HOME 설정 (영구적)
echo 'export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home' >> ~/.bashrc
source ~/.bashrc
...

다음 단계는?

이제 Airflow 3.1.3이 실행 중이므로, 다음에 탐색해 볼 몇 가지 사항은 다음과 같습니다:

• 첫 번째 DAG 작성하기 — $AIRFLOW_HOME/dags/ 디렉토리에 Python 파일을 생성하여 워크플로 (workflow)를 정의하세요.
• 새로운 UI 탐색하기 — Airflow 3는 개선된 DAG 뷰를 제공하는 완전히 새로운 React 기반 인터페이스를 탑재하고 있습니다.
• Assets에 대해 알아보기 — Airflow 3는 데이터 인지형 스케줄링 (data-aware scheduling)을 위해 Assets (이전의 Datasets)를 도입했습니다.
• PostgreSQL 설정하기 — 운영 환경 (production)에서 사용하기 위해 Airflow 메타데이터 백엔드 (metadata backend)를 SQLite에서 PostgreSQL로 교체하세요.
• Task SDK 사용하기 — Airflow 3는 태스크 (task)를 독립적으로 작성할 수 있는 독립형 Task SDK를 제공합니다.

공식 Airflow 3 퀵 스타트 (Quick Start) 가이드는 다음을 방문하세요: https://airflow.apache.org/docs/apache-airflow/stable/start.html