[Airflow] Docker Compose로 Installation

Introduction

공식문서에 보면 released sources를 직접 로컬에 설치, Docker Image를 이용한 설치, PyPI를 이용하여 로컬에 설치하는 방법들이 있다.

PyPI 방식의 경우 로컬 computer에 pip 과 같은 python package를 활용하여 constraint files를 이용하여 설치한다. 하지만 conflict가 많이 발생할 것 같고.. conda로 가상환경 만들어줘서 설치해줘야 할 것 같다,, 기왕이면 독립된 공간이 더 좋지 않을까? 생각이 들어 Docker Image를 활용한 설치 방법을 이용하기로 했다.

참고로 Quick start는 Python pacakge 관리 uv 를 이용해서 설치하는데, 빠르게 실행하는 예시일 뿐 실제 production에서 활용하면 안 된다고 한다!

Running Airflow in Docker

Link

나는 그냥 Docker Image Pull 하면 되는 거 아닌가..? 라고 단순하게 생각했는데

공식문서에 따르면 Airflow는 distributed application이기 때문에 각 기능을 담당하는 여러 component가 존재한다.

따라서 Docker Compose enviroment에서 Airflow를 launching하는 것을 추천한다고 한다.

Airflow architecture는 아래 글을 참고하기를..!

아래 글을 먼저 읽고 설치하는 것을 적극 권장한다!!!!

2026.01.13 - [DevOps/Airflow] - [Airflow] Architecture

[Airflow] Architecture

본 글은 공식문서 Architecture Overview를 보고 작성하였습니다. IntroductionAirflow는 workflows를 build하고 실행할 수 있게 해주는 platform이라고 했다.Airflow의 architecture에는 어떤 Component로 구성되어 있고,

letsgo8justice.tistory.com

🤔 그냥 Docker Image를 Pull해서 사용하면 안 됨?

Q. 하나의 Image로 Container를 생성하지 않고, 각 기능을 담당하는 Container들을 따로 생성하는 이유는 무엇일까?

Gemini) 그것이 MSA의 기본이다. 말한대로 Image 안에 webserver, schedular, worker 기능이 다 들어 있다.

분리해서 실행하는 이유는 1. 장애 격리 (Webserver가 죽어도 Worker가 계속 일하도록) 2. 효율적인 자원 배분 (Task가 많아지만 Worker만 늘리게) 3. 업데이트 용이(DB를 바꾸고 싶으면 DB 컨테이너만 바꾼다)와 관련 장점이 있기 때문이다.

또한 동일한 Image를 사용하더라도 실행 시 command를 다르게 주어 각 Component의 역할에 대응되는 Container가 실행된다. 참고로 똑같은 Image를 6개의 Container에 복제하는게 아니라 원본 Image는 하나만 두고 6개의 Container가 read mode로 공유하는 방식이다.

만약 하나의 Airflow Image만을 사용한다면, 각 Component를 실행하기 위해 command를 따로 입력해주거나(DB 키고, webserver 키고, schedular 키고, worker 키고) airflow standalone 이라는 command로 모든 component 처리하도록 하지만.. 이건 테스트 용의 scripts일 뿐.. Container 죽으면 다 죽는다. 그리고 SQlite DB를 사용하기 때문에 workflows로 한 번에 한 user만 접속 가능하다.

🤔 Docker Compose란? Link
multi container application을 정의하고 실행하는 tool이다. YAML file로 정의하면 된다.
즉 여러 container를 하나의 서비스 단위로 묶어서 관리하며, Container들의 통신을 위해 Virtual Network를 자동으로 생성한다.

docker-compose.yaml 파일을 보면 알겠지만 scheduler, dag processor, database 등 필요한 component를 각 container로 생성하도록 정의되어 있다.

❌ 주의) 학습과 탐색 용으로만 사용할 것!
실제 production system은 이 예시보다 훨씬 복잡한 구조가 필요하고, 현재 제공되는 docker compose files에는 production system에 필요한 security guarantees가 없다.

따라서 production에서 Airflow를 실행하고 싶다면 Kubernetes와 Helem Chart를 이용하길 적극 권장한다.

참고로 해당 follow up은 Docker 환경에서 Airflow를 CeleryExecutor로 빠르게 구축하는 예시다!

Prerequisites

Docker (메모리 최소 4GB 이상, ideally 8GB)
Docker Compose (v2.14.0)

Docker Desktop으로 Docker Compose까지 한번에 설치 가능하니 Docker Desktop을 추천한다.

참고로 MacOS에서 Docker를 위한 메모리 사용 가능한 default mermory 양이 Airflow를 시작하고 실행하는데 충분하지 않다고 한다!

~~나는 Windows OS다.~~

Fetching `docker-compose.yaml`

curl -LfO 'https://airflow.apache.org/docs/apache-airflow/3.1.5/docker-compose.yaml'

위와 같은 명령어를 cmd에 입력하여 docker-compose를 배포하기 위한 yaml 파일을 가져온다. (cmd 창은 관리자 권한으로 열것)

docker-compose.yaml

x-airflow-common: # Airflow Container들이 공통으로 사용하는 image, volumes, variable을 한 곳에 정의한 template
    image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:3.1.5}
    volumes:
        - ${AIRFLOW_PROJ_DIR:-.}/dags:/opt/airflow/dags
        - ${AIRFLOW_PROJ_DIR:-.}/logs:/opt/airflow/logs
        - ${AIRFLOW_PROJ_DIR:-.}/config:/opt/airflow/config
        - ${AIRFLOW_PROJ_DIR:-.}/plugins:/opt/airflow/plugins
services:
    airflow-scheduler
        <<: *airflow-common # template 내용을 해당 서비스로 가져오는 복사 기능
        command: scheduler
    airflow-dag-processor
        <<: *airflow-common
        command: dag-processor
    airflow-api-server
        <<: *airflow-common
        command: api-server
    airflow-worker
        <<: *airflow-common
        command: celery worker
    airflow-triggerer
        <<: *airflow-common
        command: triggerer
    postgres: # 외부 dependency
        image: postgres:16
        volumes:
              - postgres-db-volume:/var/lib/postgresql/data
    redis: # 외부 dependency
        image: redis:7.2-bookworm

해당 file을 보면..

1. 최신 Airflow Image를 사용하고 있고.

2. 각 service들(component)을 container로 생성하기 위해 공통 airflow image에서 command로 component를 호출하도록 작성되어 있다.

3. CeleryExecutor로 실행하기 때문에 airflow-worker가 celery worker를 호출하는 것을 알 수 있다.

여기서 정의한 service들은 다음과 같다.

airflow-scheduler: 모든 tasks와 Dags를 monitoring하고 특정 task instances의 dependencies가 완료되었는지 확인하고 tasks를 trigger한다.
airflow-dag-processor: Dag processor는 python Dag files를 parsing(해석)한다. scheduler가 이해할 수 있게 변환시켜준다.
airflow-api-server: http://localhost:8080에서 사용 가능한 api server. 즉 UI를 통해서 DAG 관리하고 모니터링 하는 REST API를 처리
airflow-worker: scheduler에게 할당받은 tasks를 실행하는 worker
airflow-triggerer: diferrable tasks(지연 가능 tasks)를 위한 event loop를 실행한다.특정 조건이 충족될 때까지 대기해야 하는 task가 worker resource를 점유하지 않도록 분리한다. 비동기 방식으로 감시하고 처리한다!
airflow-init: system 시작 전 DB schema 생성 등 초기 설정을 위한 초기화 service
postgres: 모든 시스템 메타데이터를 저장하기 위한 RDBMS
redis: scheduler에서 worker 사이 messages를 전달하는 broker. scheduler의 messages를 일시적으로 저장하기 위한 인메모리(In-memory) DB다.즉 Message Queue의 역할을 한다.
flower(Options): Celery Executor를 사용할 때, 워커(Worker)와 작업 큐(Redis)의 상태를 실시간으로 모니터링하기 위한 대시보드 도구 . http://localhost:5555 에서 사용 가능하다.
* 만약 사용하고 싶다면 --profile flower option을 추가하면 된다.

Container의 몇몇 directories는 volume mount되어 있다. mount 되어 있다는 것은 내 local computer와 container가 synchronized(동기화) 되어 contents를 저장한다는 뜻이다.

컨테이너가 멈춰도 정보를 보존하기 위해..!

./dags - Dag files들을 여기서 생성하면 된다.
./logs- task 실행과 scheduler의 logs가 포함.
./config- cluster policy를 구성하기 위해 custom log parser를 추가하거나 airflow_local_settings.py를 추가한다
./plugins - custom plugins 를 여기에 추가하면 된다.

Initializing Environment

이제 진짜 시작!!!!!!

하기에 앞서, 처음 Airflow를 사용한다면, 몇 가지 env 구축을 해야한다. (ex. 필요한 file, dir, 초기 db 생성)

Setting the right Airflow user

위에서 봤듯이 docker-compose.yaml에서 volume 설정을 했기 때문에 container 내부 data를 local과 동기화하여 data를 보존할 수 있다.

이때 Airflow의 docker container 내부 user ID의 default 값은 50000이다. 만약 local과 container user ID를 맞춰주지 않는다면, 나중에 local에서 파일 삭제, 변경 시 권한 문제 (Permission Denied)가 발생할 수 있다. 때문에 권한 충돌을 미리 예방해줘야 한다!

Linux

Linux를 사용한다면, host user ID를 알아야하고 group id는 반드시 0으로 설정해야 한다. 그렇지 않으면 data, logs, config, plugins folder에서 생성되는 file들이 root 권한으로 생성된다. 이를 방지하기 위해 .env 파일에 현재 user ID를 저장한다.

mkdir -p ./dags ./logs ./plugins ./config
echo -e "AIRFLOW_UID=$(id -u)" > .env

folder들을 생성하고 현재 user ID를 .env 파일에 저장한다.

Other OS

다른 OS의 경우, AIRFLOW_UID가 설정되지 않았다는 warning이 뜰 수 있지만, 사실 무시해도 된다!

하지만 Terminal에 warning을 없애고 싶다면, docker-compose.yaml 파일과 같은 위치에 .env 파일을 생성하고 아래 내용을 입력하면 된다.

AIRFLOW_UID=50000

Initialize the database

database migrations(DB schema를 생성 및 초기화)를 실행하고 첫 번째 user account를 생성해야 한다!

docker compose up airflow-init

docker-compose.yaml이 있는 folder 내에서 Terminal에 command를 실행해보자. 이때 초기화를 위한 airflow-init 컨테이너 하나만 실행된다.

log들을 보면

redis, postgres, airflow-init(airflow 공통 Image) Image Pulling
Network(가상 Network를 생성해서 각 Container들이 서로 통신하기 위함), Volume(Postgres data를 영구 저장하기 위함), 3개의 Continaer들 생성

initialization이 완료되고 message가 아래와 같이 뜨면 성공한 것이다.

airflow-init-1 exited with code 0

참고로 airflow-init 컨테이너 는 초기화 작업 후에 스스로 Exit한다!

관련 files, folders, plug-ins도 생성된 것을 확인할 수 있다.

참고로 생성된 administrator account는

ID: airflow
password: airflow

나중에 UI에서 login할 때 사용하면 된다.

💡Cleaning-up environment

이 guide는 quick-start 용이고 실제 production에서 사용하도록 설계되지 않았다..

따라서 어떤 문제가 발생한다면 싹 다 지우고 처음부터 다시 시작하길 추천.. (역시 껐다 키는게 최고여)

- docker-compose.yaml 파일이 있는 directory에 docker compose down --volumes --remove-orphans command를 실행
- 그리고 그 directory 삭제
- 다시 docker-copose.yaml 파일 다운받고 이 guide 처음부터 다시 시작

Running Airflow

자 이제 모든 service들을 싹다 돌려서 진짜 airflow를 실행시켜보자

docker compose up

사실 airflow-init 도 다시 실행되지만, 아마 script 상에서 이미 필요한 설정들이 완료되었으면 바로 종료될 것이다!

log를 보면 다른 component의 container들(알록달록함)이 실행되는 것을 볼 수 있다.

docker ps

다른 terminal 창을 열고 다른 containers가 잘 실행되고 있는지 확인해보자. STATUS에 healthy라고 뜨는지 잘 확인해볼 것..!

_docker-compose.yaml_에 설정한 component의 container들이 실행되고 있다!

Accessing the environment

Airflow를 시작한 후, interact하는데 3가지 방법이 있다.

1. CLI commands로 실행하는 방법

2. Web UI로 접속하는 방법

3. REST API를 사용하는 방법

나는 2번 방식대로 http://localhost:8080으로 접속해서 ID와 password에 airflow를 입력해서 접속할 것이다.

만약 CLI commands로 실행시키고 싶다면 docker-compose.yaml에 정의된 service(airflow-*)들 중에 하나를 이용해야 한다.

docker compose run airflow-worker airflow info

예를 들어 airflow info를 실행시키고 싶다면, 위와 같이 (귀찮게) 명령어를 입력시킬 수 있다..

Mac OS나 Linux OS인 경우에는 Wrapper scripts (공식문서 참고)를 다운 받아서 실행시키면 된다.

./airflow.sh info

그러면 위의 명령어가 이렇게 간단해진다!!

Cleaning up

만약 아예 다 삭제하고 초기화하고 싶다면 다음 명령어를 실행시키면 된다.

docker compose down --volumes --rmi all

volume, image까지 삭제한다.. (태초 마을로..)

마치며

기록하면서 실행시키는데 4시간동안 쓴 글 랙 걸려서 다 날려먹었다.

중간중간 저장하는 습관을 기르도록 하자. 허허허

'DevOps > Airflow' 카테고리의 다른 글

[Airflow] Architecture (0)	2026.01.13
[Airflow] Overview (0)	2026.01.06

Introduction

Running Airflow in Docker

🤔 그냥 Docker Image를 Pull해서 사용하면 안 됨?

Prerequisites

Fetching docker-compose.yaml

Initializing Environment

Setting the right Airflow user

Initialize the database

Running Airflow

Accessing the environment

Cleaning up

마치며

'DevOps > Airflow' 카테고리의 다른 글

티스토리툴바

Fetching `docker-compose.yaml`