빠른 시작

빠른 시작 (Quick Start)

이 빠른 시작 가이드는 로컬 머신에서 Airflow standalone 인스턴스를 부트스트랩하는 방법을 도와줘요. 설치부터 UI 접근까지 한 번에 따라갈 수 있답니다.

출처: 문서

본문

이 빠른 시작 가이드는 로컬 머신에서 Airflow standalone 인스턴스를 부트스트랩하는 데 도움을 줘요.

Note

성공적인 설치에는 Python 3 환경이 필요해요. Airflow 3.2.0부터 Airflow는 Python 3.10, 3.11, 3.12, 3.13, 3.14를 지원해요.

공식적으로 지원되는 설치 방법은 pip 또는 uv예요.

재현 가능한 방식으로 Airflow를 설치하려면 pip install apache-airflow[EXTRAS]==AIRFLOW_VERSION --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-AIRFLOW_VERSION/constraints-PYTHON_VERSION.txt"를 실행해요. 예를 들어 pip install "apache-airflow[celery]==3.0.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.10.txt"처럼요. 명령 앞에 uv를 붙여 훨씬 더 빠른 uv를 사용할 수도 있어요.

poetry나 pip-tools 같은 다른 도구로 성공한 사례가 있긴 하지만, 특히 constraint vs requirements 관리 측면에서 pip나 uv와 같은 워크플로를 공유하지는 않아요. Poetry나 pip-tools로의 설치는 현재 지원되지 않아요.

이런 도구로 Airflow를 설치하려면 constraint 파일을 사용해 도구에서 요구하는 적절한 형식과 워크플로로 변환해야 해요.

이 가이드는 Python 환경과 의존성을 관리하는 빠르고 현대적인 도구인 uv를 사용해 Apache Airflow를 빠르게 설정하도록 도와줘요. uv는 설치 과정을 쉽게 만들고 매끄러운 설정 경험을 제공해요.

Windows를 사용한다면 WSL2(Windows용 Linux 환경)를 사용해야 해요.

wsl --install

  1. Airflow Home 설정 (선택 사항):

    Airflow는 홈 디렉터리가 필요하며 기본적으로 ~/airflow를 사용해요. 하지만 원한다면 다른 위치를 설정할 수 있어요. AIRFLOW_HOME 환경 변수가 Airflow에 원하는 위치를 알려주는 데 사용돼요. 이 환경 변수 설정 단계는 설치 전에 해두어야 설치 과정이 필요한 파일을 저장할 위치를 알 수 있어요.

    export AIRFLOW_HOME=~/airflow

  2. uv를 사용해 가상 환경에 Airflow를 설치해요. uv는 venv를 자동으로 만들어주는 더 빠른 대안이에요. pip와 venv를 사용하는 것에 비해 효율적인 대안이에요.

    uv 설치: uv 설치 가이드

    uv로 가상 환경을 만드는 방법은 여기 문서를 참고하세요: uv로 로컬 virtual environment 생성·유지하기

pip와 venv로 설치하려면 다음 단계를 수행해요. Debian/Ubuntu 시스템에서는 Python이 외부 관리 환경(PEP 668)을 강제할 수 있으므로, pip install 명령을 실행하기 전에 가상 환경을 사용하세요:

# For Windows after WSL2 install, restart computer, then in WSL Ubuntu terminal
sudo apt update
sudo apt install python3-pip python3-venv

# Go to Linux home directory (not Windows mount)
cd ~

# Create airflow directory
mkdir -p ~/airflow
cd ~/airflow

# Create virtual environment
python3 -m venv airflow_venv

# Activate
source airflow_venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install Airflow with correct Python version constraints
pip install apache-airflow[celery]==3.1.0 --constraint https://raw.githubusercontent.com/apache/airflow/constraints-3.1.0/constraints-3.12.txt

# Verify installation
airflow version

  1. 전달하는 URL을 기준으로 결정되는 constraint 파일을 사용해 Airflow를 설치해요:

    AIRFLOW_VERSION=3.1.1

# Extract the version of Python you have installed. If you're currently using a Python version that is not supported by Airflow, you may want to set this manually.
# See above for supported versions.
PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"

CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
# For example this would install 3.0.0 with python 3.10: https://raw.githubusercontent.com/apache/airflow/constraints-3.3.2/constraints-3.10.txt

uv pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"

  2. Airflow Standalone 실행하기:

    airflow standalone 명령은 데이터베이스를 초기화하고, 사용자를 만들고, 모든 컴포넌트를 시작해요.

    airflow standalone

    Note

    Airflow 3.x에서는 airflow standalone 실행 시 관리자 비밀번호가 항상 터미널 출력에 표시되지는 않아요.

    비밀번호는 자동 생성되어 다음에 저장돼요:

    $AIRFLOW_HOME/simple_auth_manager_passwords.json.generated

    조회하려면 다음을 실행해요:

    cat ~/airflow/simple_auth_manager_passwords.json.generated

    이 비밀번호로 기본 자격 증명 대신 웹 인터페이스에 로그인해요.

  3. Airflow UI 접근하기:

    브라우저에서 localhost:8080을 방문해 터미널에 표시된 관리자 계정 세부 정보로 로그인해요. 홈 페이지에서 example_bash_operator DAG을 활성화해요.

이 명령들을 실행하면 Airflow는 $AIRFLOW_HOME 폴더를 만들고 기본값이 담긴 "airflow.cfg" 파일을 생성해 빠르게 시작할 수 있게 해줘요. 환경 변수로 기본값을 재정의할 수 있으며, 이는 구성 참조를 참고하세요. $AIRFLOW_HOME/airflow.cfg 파일이나 UI의 Admin->Configuration 메뉴에서 파일을 확인할 수 있어요. webserver의 PID 파일은 $AIRFLOW_HOME/airflow-api-server.pid 또는 systemd로 시작한 경우 /run/airflow/airflow-webserver.pid에 저장돼요.

성장하고 Airflow를 프로덕션에 배포하게 되면, 여기서 사용한 standalone 명령에서 벗어나 컴포넌트를 개별적으로 실행하고 싶을 거예요. 자세한 내용은 프로덕션 배포에서 읽을 수 있어요.

몇 가지 Task 인스턴스를 트리거하는 명령이 아래에 있어요. 아래 명령을 실행하면서 example_bash_operator DAG에서 작업 상태가 바뀌는 것을 볼 수 있을 거예요.

# run your first task instance
airflow tasks test example_bash_operator runme_0 2015-01-01
# run a backfill over 2 days
airflow backfill create --dag-id example_bash_operator \
    --from-date 2015-01-01 \
    --to-date 2015-01-02

모든 기능이 포함된 standalone 명령 대신 Airflow의 개별 부분을 직접 실행하려면 다음을 실행할 수 있어요:

airflow db migrate

airflow users create \
    --username admin \
    --firstname Peter \
    --lastname Parker \
    --role Admin \
    --email [email protected]

airflow api-server --port 8080

airflow scheduler

airflow dag-processor

airflow triggerer

Note

airflow users 명령은 Flask AppBuilder (FAB) auth manager가 활성화된 경우에만 사용할 수 있어요.

다음은 무엇일까요? (What's Next?)

이 시점부터 더 많은 예시를 보려면 튜토리얼 섹션으로, 실제로 직접 해보고 싶다면 How-to 가이드 섹션으로 가면 돼요.

더 알아보기 (Learn more)