외부 연동을 위한 Airflow 필수 CLI 커맨드

1. CLI 연동의 필요성

Airflow 1.x 버전 환경 당시 플랫폼의 외부 UI 모듈에서 Airflow 워크플로우를 원격으로 제어할 수 있는 쓸만한 REST API가 없었습니다. 백엔드에서 DAG 진행 상태를 폴링(Polling)하거나 특정 Task를 트리거하기 위해, 차선책으로 Airflow 컨테이너(또는 서버) 내부의 CLI(Command Line Interface)를 직접 호출하여 파싱하는 방식을 채택해야 했습니다. 이를 위해 가장 자주 쓰이는 필수 CLI 커맨드들을 정리했습니다.

2. Airflow CLI 핵심 구조

Airflow CLI는 워크플로우 전주기(리스트업, 상태 조회, 트리거, 일시정지, 삭제, 테스트)를 관리할 수 있는 가장 확실한 기본 기능입니다. 특히 하이브리드 클라우드 환경으로 넘어오면서 Google Cloud Composer를 사용할 때는 로컬 airflow 명령어 대신 gcloud composer environments run 형태의 래퍼(Wrapper) 커맨드로 파라미터를 넘겨야 합니다.

3. 필수 커맨드 활용 예시 및 구현

1. 자주 사용하는 필수 CLI 커맨드 목록

명령어 (Subcommand)	사용법 예시	설명 (용도)	비고
list_dags	`airflow list_dags [-r]`	등록된 전체 DAG 리스트 출력	`-r` 사용 시 DagBag 상세 출력
list_tasks	`airflow list_tasks {dag_id}`	특정 DAG에 속한 Task 리스트 출력
dag_state	`airflow dag_state {dag_id} {execution_date}`	특정 날짜의 DAG 실행 상태(Success/Run..)
task_state	`airflow task_state {dag_id} {task_id} {execution_date}`	특정 날짜의 Task Instance 상태
trigger_dag	`airflow trigger_dag {dag_id}`	즉시 DAG 수동 실행 트리거
pause	`airflow pause {dag_id}`	DAG 스케줄링 일시 정지
unpause	`airflow unpause {dag_id}`	정지된 DAG를 다시 시작
delete_dag	`airflow delete_dag {dag_id}`	DB에서 DAG 관련 레코드 모두 삭제	UI 삭제 오류 시 유용
test	`airflow test {dag_id} {task_id} {execution_date}`	특정 Task만 의존성 무시하고 로컬 테스트	DAG 개발 중 필수
run	`airflow run {dag_id} {task_id} {execution_date}`	단일 Task Instance를 강제로 스케줄러를 통해 실행	재작업 시 활용

2. [팁] Google Cloud Composer (GCP) 환경에서 CLI 사용법

클라우드 관리형인 GCP Composer에서는 gcloud 명령어로 Airflow CLI를 래핑해서 사용합니다. 이때 파라미터(Args)를 넘기려면 반드시 -- 뒤에 붙여야 파서가 엉키지 않습니다.

예시: -r 플래그를 넘겨 DAG 리스트 추출하기

bash


$ gcloud composer environments run sf-composser-test --location us-central1 list_dags -- -r

4. 마무리 및 팁

REST API가 약했던 시절, 이 CLI 아웃풋(stdout)을 파싱해서 백엔드 서비스의 상태 객체로 매핑하는 코드를 짜면서 “오픈소스 생태계 발전 속도를 기대하느니 CLI 파싱이 속편하다”고 느꼈던 경험입니다. 물론 최신 Airflow 2.x에서는 이 모든 CLI 기능들이 Stable REST API로 제공되므로 굳이 CLI를 파싱하는 레거시 패턴을 따라갈 필요는 없습니다. 다만, Airflow 서버 쉘에서 직접 강제 복구를 해야 하는 장애 상황에서는 여전히 CLI가 엔지니어의 가장 강력한 무기가 됩니다.