Apache Airflow를 시작하는 가장 쉬운 방법, Astro CLI

choo121600 · 3월 21, 2025, 10:19오전

Apache Airflow에 대해 자주 이야기가 나오는 것이 있습니다.

Airflow를 시작하기 어렵다.
로컬 환경에서 세팅하기 어렵다.

이런 이야기의 배경에는 설치부터 공식 문서에서 방대한 양의 세팅 관련 문서를 마주했던 경험과,
실행 및 테스트를 위해 추가적인 도구(Airflow Breeze) 혹은 명령어를 추가로 학습해야 했고 그마저도 사용하기 쉬운 것과는 거리가 멀었기 때문입니다.

이러한 이유로 많은 사람들이 "Airflow를 어렵다"고 느낍니다.
그런데 만약 Apache Airflow를 쉽게 설치하고, 단 몇 개의 명렁어만으로도 실행과 테스트를 할 수 있다면 어떨까요?

Apache Airflow 생태계에 많은 기여를 해온 Astronomer은 이 문제를 해결하기 위해 Apache Airflow를 설치하는 가장 쉬운 방법, Astro CLI라는 것을 개발했습니다.

그리고 이를 오픈소스로 공개하여 누구나 손쉽게 Airflow를 설치하고 사용할 수 있게 되었습니다.

이 글을 통해서 Astro CLI를 어떻게 사용할 수 있는지 알아보도록 하겠습니다.

Astro CLI 설치

Astro CLI는 MacOS, Window, Linux 모두 사용할 수 있습니다.
설치는 공식 홈페이지를 참고하여 설치할 수 있습니다.

설치가 완료되었는지 아래의 명령어를 통해 정상적으로 설치되었는지 확인해봅시다.

astro -h

Astro CLI 미리보기

과연 얼마나 쉽게 실행이 가능하길레 이렇게 호들갑인가 싶을 것입니다.
AstroCLI를 사용하면 단 3개의 직관적인 명령어만으로 프로젝트를 세팅하고 실행하고 중지할 수 있습니다.

astro dev init
astro dev start
astro dev stop

astro dev init && astro dev start

image.png1097×855 89.8 KB
localhost:8080으로 Airflow UI 가 나오면 Username과 Password에admin과 admin을 쳐서 들어갑니다.

image.png2032×1167 108 KB

image.png2032×1167 137 KB
astro dev stop

image.png1097×855 98.3 KB

한 번이라도 Airflow를 직접 세팅하느라 어려움을 겪으셨던 분이나,
처음 공부하실 때 공식문서의 “Installation of Airflow”를 보고 벽을 느끼셨던 분들은 이것이 얼마나 감동적인 경험인지 공감하실 것입니다.

그럼 조금 더 자세히 알아보도록 하겠습니다.

Astro CLI 를 사용한 Airflow 프로젝트 시작하기

프로젝트 폴더에서 astro dev init을 실행하면 프로젝트의 기본 디렉토리 구조가 생성됩니다.

디랙토리 구조는 다음과 같습니다:

.
├── .env                    # 로컬 환경 변수 설정 파일
├── dags                    # DAG 파일을 저장하는 디렉토리
│   └── exampledag.py       # 간단한 예제 DAG
├── Dockerfile              # Astro Runtime Docker 이미지
├── include                 # 기타 포함할 파일을 저장하는 디렉토리
├── plugins                 # Airflow 플러그인 저장소
├── tests                   # pytest로 실행할 DAG 유닛 테스트 파일 폴더
│   └── test_dag_example.py # 간단한 예제 테스트
├── airflow_settings.yaml   # Airflow connections, variables and pools 설정 파일
├── packages.txt            # OS 수준 패키지 목록
└── requirements.txt        # Python 패키지 목록

connections, variables, pools 설정하기

Airflow의 connection, variable, pools를 설정하는 방법에는 두 가지가 있습니다.
이 과정은 Astro CLI를 사용하지 않더라도 동일하기 때문에 이미 익숙할 수 있으므로 간단히 넘어가겠습니다.

AirflowUI를 통한 설정

Airflow UI에서 직접 설정할 수 있습니다. UI에서 “Admin” → "Connections/Variables/Pools"로 이동해서 설정하시면 됩니다.

airflow_settings.yaml를 통해 설정

airflow_settings.yaml 파일을 통해 아래와 같이 connections, variables, pools을 설정할 수 있습니다.

airflow:
  connections:
    - conn_id:
      conn_type:
      conn_host:
      conn_schema:
      conn_login:
      conn_password:
      conn_port:
      conn_extra:
        example_extra_field: example-value
  pools:
    - pool_name:
      pool_slot:
      pool_description:
  variables:
    - variable_name:
      variable_value:

환경변수 설정

Airflow를 사용할 때, 일반적으로 airflow.cfg 파일을 사용합니다.
하지만 Astro CLI를 사용한 프로젝트는 .env 파일에 설정된 값을 기반으로 airflow.cfg를 생성하기 떄문에 .env 파일을 사용하여 환경변수를 설정합니다.
따라서 별도로 airflow.cfg를 수정하거나 설정할 필요가 없습니다.

환경변수를 확인하려면 아래 명령어로 확인할 수 있습니다:

astro dev bash --scheduler

cat airflow.cfg

이 명령어로 생성된 airflow.cfg 파일의 내용을 확인할 수 있습니다.

Airflow의 특정 버전으로 프로젝트 생성하기

아무 옵션없이 astro dev init을 실행했을 때는 설치된 Astro CLI에 기본 설정된 astro runtime이 지원하는 가장 최신의 Airflow 버전으로 프로젝트가 생성이 됩니다.
하지만 특정 버전의 Airflow로 프로젝트를 생성할 필요가 있을 때도 있습니다.

이럴 경우를 위해, Astro CLI는 두 가지 방법으로 특정 버전의 Airflow 프로젝트를 생성할 수 있습니다.

Astro Runtime 버전을 고정하여 프로젝트 초기화

아래의 명령어를 통해 astro runtime 버전을 4.1.0 으로 고정하고 프로젝트를 생성해보겠습니다.

astro dev init --runtime-version 4.1.0

astro runtime release note 에서 Astro Runtime 4.1.0 이 Apache Airflow 2.2.4버전을 지원하고 있는 것을 확인할 수 있습니다.

실제로 Astro Runtime의 버전을 고정하여 만든 프로젝트의 Airflow 버전이 2.2.4인 것을 확인할 수 있습니다.

Airflow 버전을 고정하여 프로젝트 초기화

그럼 이제 단순하게 Airflow 버전을 고정하여 프로젝트 초기화를 해봅시다.
아래의 명령어를 통해 Airflow 2.3.0으로 프로젝트를 생성해봅시다.

astro dev init --airflow-version 2.3.0

이 명령어들을 사용하여, 로컬 개발환경을 프로덕션 환경의 Airflow 버전과 맞춰줄 수 있습니다.

Astro CLI 템플릿을 활용하여 프로젝트 시작하기

Astro CLI는 Airflow 학습을 위한 다양한 템플릿을 제공합니다.

astro dev init -t

명령어를 실행하면 템플릿 목록이 나오며, 원하는 템플릿을 선택하고 Enter 키를 누르면 자동으로 구성이 됩니다.

저는 예시로 etl을 선택하여 4를 입력하고 Enter 키를 눌러보았습니다.

그럼 아래와 같이 템플릿이 적용되어 디렉토리가 구성이 된 것을 확인할 수 있습니다.

단위 테스트

Astro CLI를 사용하면 다음의 DAG 단위 테스트 Astro CLI 명령어를 활용하여 개발한 DAG가 정상적으로 동작하는지 빠르게 확인할 수 있습니다.

astro dev parse
astro dev pytest

astro dev parse 명령은 DAG를 구문 분석하여 기본 syntax나 import 오류가 없는지, Airflow UI에서 성공적으로 렌더링할 수 있는지 간단하게 아래와 같이 확인할 수 있습니다.

astro dev pytest명령은 tests 디렉토리 안에 있는 모든 테스트를 진행합니다.
아래와 같이 tests 디렉토리 안에 예시로 들어있는 test_dag_example.py 를 수행한 내용을 확인할 수 있습니다.

마무리하며

이제 Airflow를 시작하는 것은 더 이상 어려운 것이 아닙니다.
Astro CLI를 사용하면 단 몇 가지의 명령어만으로 쉽게 로컬 Airflow 개발 환경을 구축하고 실행, 테스트할 수 있습니다.

Astro CLI를 사용하여 더욱 간편하게 Airflow를 시작해보세요