아파치 에어플로우(Apache Airflow) 설치 가이드

아파치 에어플로우는 데이터 파이프라인을 프로그래밍 방식으로 작성, 예약 및 모니터링할 수 있는 플랫폼입니다. 이 블로그에서는 다양한 환경에서 에어플로우를 설치하는 방법을 알아보겠습니다.

목차

1. 아파치 에어플로우란?
2. 리눅스/맥에서 설치하기
3. 도커를 이용한 설치하기
4. 윈도우에서 설치하기
5. 트러블슈팅

1. 아파치 에어플로우란?

아파치 에어플로우(Apache Airflow)는 워크플로우의 작성, 예약 및 모니터링을 프로그래밍 방식으로 수행할 수 있는 오픈소스 플랫폼입니다. 데이터 엔지니어링, ETL(Extract, Transform, Load) 작업, 배치 처리 등의 작업을 효율적으로 관리하기 위해 설계되었습니다.

주요 특징

• Python 기반의 DAG(Directed Acyclic Graph): 작업 흐름을 코드로 정의
• 웹 인터페이스: 작업 상태 모니터링, 로그 확인, 수동 실행 등의 기능 제공
• 확장성: 다양한 플러그인과 확장 프로그램 지원
• 스케줄링: 작업의 예약 및 주기적 실행 관리
• 유연한 통합: AWS, GCP, Azure 등 다양한 플랫폼과의 연동 지원

주요 구성 요소

• Webserver: 웹 UI 제공 (기본 포트: 8080)
• Scheduler: 모든 작업과 DAG를 모니터링하고 실행
• Worker: 스케줄러로부터 할당받은 작업을 실행
• Database: 메타데이터 저장 (기본: SQLite, 프로덕션: PostgreSQL, MySQL 등)
• Executor: 작업 실행 방식 정의 (기본: SequentialExecutor, 프로덕션: CeleryExecutor, KubernetesExecutor 등)

2. 리눅스/맥에서 설치하기

리눅스나 맥에서는 에어플로우를 직접 설치하는 것이 가장 간단한 방법입니다.

사전 준비

• Python 3.7 이상
• pip (Python 패키지 관리자)

설치 단계

1) 가상환경 생성 및 실행

Copy# pyenv와 virtualenv를 사용하는 경우
$ pyenv virtualenv 3.8.6 venv-airflow
$ pyenv activate venv-airflow

# 또는 python3 venv를 사용하는 경우
$ python3 -m venv venv-airflow
$ source venv-airflow/bin/activate

2) 환경 변수 설정

Copy# AIRFLOW 홈 디렉토리 설정
$ export AIRFLOW_HOME=~/airflow

3) Airflow 설치

Copy$ pip install apache-airflow

추가 패키지가 필요한 경우 다음과 같이 설치할 수 있습니다:

Copy$ pip install apache-airflow[postgres,s3]

4) DB 초기화

Copy$ airflow db init

이 명령어는 기본적으로 SQLite 데이터베이스를 초기화하고, 홈 디렉토리에 airflow 폴더와 설정 파일들을 생성합니다.

5) 유저 계정 생성

Copy$ airflow users create \
    --username admin \
    --firstname Admin \
    --lastname User \
    --role Admin \
    --password admin \
    --email admin@example.com

6) Webserver 실행

Copy$ airflow webserver --port 8080

7) 별도의 터미널에서 Scheduler 실행

Copy$ airflow scheduler

예제 DAG 숨기기 (선택사항)

기본적으로 에어플로우는 예제 DAG를 로드합니다. 이를 비활성화하려면:

1. ~/airflow/airflow.cfg 파일을 열기
2. load_examples = True를 load_examples = False로 변경
3. airflow db reset으로 DB 초기화 (주의: 기존 데이터 삭제)
4. 다시 유저 계정 생성 후 웹서버와 스케줄러 실행

3. 도커를 이용한 설치하기

도커(Docker)를 이용하면 에어플로우의 모든 구성 요소를 컨테이너화하여 쉽게 관리할 수 있습니다.

사전 준비

• Docker Community Edition(CE) 설치 (최소 4GB 메모리 권장)
• Docker Compose v1.29.1 이상

설치 단계

1) docker-compose.yaml 파일 다운로드

Copy$ curl -LfO 'https://airflow.apache.org/docs/apache-airflow/2.5.1/docker-compose.yaml'

2) 필요한 디렉토리 생성

Copy$ mkdir -p ./dags ./logs ./plugins ./config

3) .env 파일 생성 (Linux/macOS)

Copy$ echo -e "AIRFLOW_UID=$(id -u)" > .env

윈도우에서는 다음과 같이 직접 .env 파일을 만들고 내용을 추가합니다:

AIRFLOW_UID=50000

4) 환경 초기화

Copy$ docker compose up airflow-init

이 명령어는 데이터베이스를 초기화하고 첫 번째 관리자 사용자(기본 사용자 이름과 비밀번호는 모두 'airflow')를 생성합니다.

5) 에어플로우 서비스 시작

Copy$ docker compose up

또는 백그라운드에서 실행하려면:

Copy$ docker compose up -d

6) 웹 UI 접속

브라우저에서 http://localhost:8080으로 접속하면 에어플로우 웹 인터페이스에 접근할 수 있습니다.

• 기본 사용자 이름: airflow
• 기본 비밀번호: airflow

7) (선택) Flower UI 실행

Celery 작업 모니터링을 위한 Flower UI를 실행하려면:

Copy$ docker compose --profile flower up

Flower UI는 http://localhost:5555에서 접근할 수 있습니다.

8) 에어플로우 서비스 중지

Copy$ docker compose down

모든 볼륨과 이미지를 함께 삭제하려면:

Copy$ docker compose down --volumes --rmi all

도커 이미지 커스터마이징

추가 패키지가 필요한 경우 다음과 같이 Dockerfile을 생성하여 이미지를 커스터마이징할 수 있습니다:

1. docker-compose.yaml 파일에서 build: . 주석 해제
2. 동일한 디렉토리에 Dockerfile 생성:

CopyFROM apache/airflow:2.5.1-python3.8
RUN pip install apache-airflow-providers-snowflake

1. 이미지 빌드:

Copy$ docker compose build

1. 컨테이너 실행:

Copy$ docker compose up

4. 윈도우에서 설치하기

에어플로우는 공식적으로 윈도우 설치를 지원하지 않습니다. 하지만 다음 두 가지 방법으로 윈도우에서 에어플로우를 실행할 수 있습니다:

A. Docker를 이용한 설치

위의 "도커를 이용한 설치하기" 섹션을 참조하세요. Docker Desktop for Windows를 설치한 후 동일한 방법으로 진행할 수 있습니다.

B. WSL(Windows Subsystem for Linux)을 이용한 설치

WSL은 윈도우에서 리눅스 환경을 실행할 수 있게 해주는 기능입니다.

1) WSL 설치하기

PowerShell을 관리자 권한으로 실행하고 다음 명령어 입력:

Copywsl --install

재부팅 후 Ubuntu 등의 Linux 배포판이 설치됩니다.

2) WSL 환경에서 패키지 업데이트

Copy$ sudo apt update && sudo apt upgrade
$ sudo apt-get install software-properties-common
$ sudo apt-add-repository universe
$ sudo apt-get update

3) Python 환경 설정

Copy# Python3 설치
$ sudo apt install python3 -y

# pip 설치
$ sudo apt install python3-pip -y

# pip 업그레이드
$ sudo pip3 install -U pip

4) Airflow 설치

Copy$ export SLUGIFY_USES_TEXT_UNIDECODE=yes
$ pip3 install apache-airflow

5) AIRFLOW_HOME 환경 변수 설정

Copy$ nano ~/.bashrc

파일 끝에 다음 줄 추가:

export AIRFLOW_HOME=~/airflow

변경사항 적용:

Copy$ source ~/.bashrc

6) Airflow DB 초기화

Copy$ airflow db init

7) 관리자 계정 생성

Copy$ airflow users create \
    --username admin \
    --firstname Admin \
    --lastname User \
    --role Admin \
    --password admin \
    --email admin@example.com

8) Webserver 및 Scheduler 실행

Copy# 웹서버 실행
$ airflow webserver --port 8080

# 새 터미널에서 스케줄러 실행
$ airflow scheduler

5. 트러블슈팅

Docker 관련 문제

문제 1: "Top level object in './docker-compose.yaml' needs to be an object not ''"

해결책: docker-compose.yaml 파일이 제대로 저장되지 않았을 수 있습니다. 파일을 다시 다운로드하거나 내용을 확인하세요.

문제 2: "docker.errors.DockerException: Error while fetching server API version"

해결책: Docker 데스크톱이 실행 중인지 확인하세요. 실행되지 않은 상태에서는 Docker 명령어가 작동하지 않습니다.

문제 3: "ERROR: for redis Cannot start service redis: driver failed programming external connectivity"

해결책: 포트 충돌이 발생했을 수 있습니다. 해당 포트를 사용 중인 다른 프로세스를 종료하거나, docker-compose.yaml 파일에서 포트 매핑을 변경하세요.

Airflow 설치 관련 문제

문제 1: "ERROR: apache-airflow 2.5.1 has requirement ... but you have ..."

해결책: 가상환경을 새로 만들고 의존성 문제가 없는 상태에서 설치하거나, 충돌하는 패키지 버전을 해결하세요.

문제 2: "ImportError: cannot import name ... from 'sqlalchemy'"

해결책: SQLAlchemy 버전 충돌 문제입니다. 다음 명령어로 해결할 수 있습니다:

Copy$ pip install -U sqlalchemy==1.4.0

문제 3: "OSError: [Errno 22] Invalid argument: '/proc/version'"

해결책: 이는 Windows 환경에서 직접 설치할 때 발생하는 문제입니다. WSL이나 Docker를 사용하세요.

마무리

지금까지 다양한 환경에서 아파치 에어플로우를 설치하는 방법을 알아보았습니다. 각 환경별 특성과 장단점을 고려하여 자신의 환경에 맞는 설치 방법을 선택하시기 바랍니다.

• 리눅스/맥: 직접 설치가 간단하며 개발 환경에 적합
• 도커: 모든 구성 요소의 쉬운 관리와 일관된 환경 제공
• 윈도우: WSL이나 Docker를 통한 간접 설치 필요

처음 에어플로우를 시작한다면 도커 설치 방법이 가장 쉽고 빠르게 시작할 수 있는 방법입니다. 프로덕션 환경에서는 Kubernetes나 관리형 서비스를 고려해보는 것도 좋은 선택입니다.

더 많은 정보는 아파치 에어플로우 공식 문서를 참조하세요.

참고 자료

• Apache Airflow 공식 문서
• Docker를 이용한 Airflow 설치 가이드
• Airflow 간단하게 설치하기
• Apache Airflow 설치 방법 정리