Airflowctl 0.1.5: 이제 Airflow CLI도 메타DB가 아니라 API로 (AIP-81)

정보공유
,
1

며칠 전 airflowctl 0.1.5가 릴리스(2026-05-26) 됐는데, 이 김에 도구 전체를 한 번 정리해서 공유합니다. 패키지명은 apache-airflow-ctl이고, 한 줄로 요약하면 기존 Airflow CLI가 메타데이터 DB에 직접 붙던 시대를 끝내고, 모든 명령을 REST API로만 돌리는 새 CLI예요. AIP-81 아래 만들어졌고, 요즘 Airflow 3.x가 밀고 있는 "control plane을 전부 API로 모은다"는 방향의 한 조각입니다.

그리고 0.1.5는 흐름상 의미가 있어요. 0.1.0~0.1.4가 버그 수정 위주의 안정화기였다면, 0.1.5는 신규 명령과 API 표면 확장이 함께 들어오면서 다시 기능 전진으로 돌아선 첫 릴리스거든요. 새 기능은 아래쪽에 따로 정리했습니다.

왜 나왔나 — 기존 CLI의 구조적 부채

이미지1_대표_터미널
이미지1_대표_터미널2640×1052 197 KB

[이미지 1. airflowctl로 원격 Airflow의 DAG run을 조회]

지금까지의 airflow CLI는 상당수 명령이 메타데이터 DB에 직접 접근해서 동작했습니다. 로컬 단일 노드에서는 편했지만, 운영 관점에선 세 가지가 계속 걸렸어요.

  • 보안: CLI를 쓰려면 DB 자격증명이 필요했고, 이건 웹 UI/API와는 다른 별도의 권한 경로였습니다.

  • 권한 일관성: UI에는 RBAC가 적용되는데 CLI는 그 바깥에 있었죠.

  • 감사(audit): CLI로 한 작업은 API 로그에 남지 않아 추적이 어려웠습니다.

airflowctl은 이 셋을 한 번에 정리합니다.

image
image2480×1200 218 KB

[이미지 2. 아키텍처 비교 다이어그램. 왼쪽 = 기존 CLI가 Metadata DB에 직접 연결 / 오른쪽 = airflowctl이 REST API(-> RBAC, Audit Log)를 경유]

airflowctl이 바꾸는 것 (핵심 3가지)

1. API 전용(API-only) 모든 명령이 Airflow의 public REST API를 통해 실행됩니다. 즉 DB 직결이 사라지고, CLI도 API 클라이언트의 하나가 됩니다. (당연히 REST API가 켜진 인스턴스가 전제예요.)

2. 키링(keyring) 기반 토큰 저장 평문 토큰/비밀번호를 파일에 두지 않고, OS 키링(macOS Keychain, Windows Credential Manager, Linux Secret Service)에 인증 토큰을 저장·조회합니다. 키링이 없는 헤드리스 환경(CI 등)에서는 명령마다 토큰을 직접 넣는 방식도 지원합니다.

3. RBAC + 감사 일원화 명령이 API를 거치므로 웹 UI와 동일한 RBAC 권한 평가를 받고, 모든 호출이 API 로그로 남아 표준 감사 메커니즘으로 추적됩니다. CLI가 그동안 보안 모델에서 빠져 있던 구멍을 메우는 셈이죠.

이미지3_키링_RBAC
이미지3_키링_RBAC2640×1052 190 KB

[이미지 3. airflowctl auth login 실행 후 토큰이 키링에 저장]

0.1.5에서 새로 들어온 것 (2026-05-26)

이번 릴리스의 헤드라인 5종입니다.

  • Dag Next Execution Command — 타임테이블 기준 다음 실행 시점을 CLI에서 바로 조회. 구형 CLI의 next_execution과 기능 패리티 회복.

  • Bulk Delete Dag Runs — 여러 DAG run을 한 번에 삭제. 여러 Task Instance를 한 번에 Clear / Mark Success·Fail / 삭제하는 기능과 짝이라, 백필 정정·정리 작업을 API 한 호출로 묶을 수 있습니다.

  • Rerun Latest Dag Version — rerun_with_latest_version 설정 계층 추가. DAG 버전관리가 있는 3.x에서 재실행 시 최신 코드로 돌릴지 / 원래 찍힌 버전으로 돌릴지를 명시 제어. 0.1.5에서 가장 “Airflow 3다운” 변화예요.

  • Positional Arguments Simplified — 자동 생성 명령의 필수 원시 파라미터를 위치 인자로, 선택 파라미터는 --flag로. dev-list lazy consensus를 따른 결정입니다.

  • JSON Backfill Payload Support — 백필 create·dry-run 페이로드를 JSON으로 전송. 복잡한 conf 전달이 견고해지고, 백필 파라미터가 기존 conf를 못 덮어쓰던 버그 수정과 한 묶음.

그리고 마케팅 5줄엔 안 들어갔지만 아키텍처적으로 더 중요한 변화가 API 레이어에 있어요. get_dag_runs / get_task_instances 엔드포인트에 커서 기반 페이지네이션이 추가됐는데, 대규모 테이블에서 offset 방식은 동시 쓰기 상황에 깨지기 쉬운 반면 커서는 일관성이 유지돼서 스케일에서 진짜로 의미 있는 변화입니다. 여기에 AIP-103(task/asset state용 Core API 엔드포인트), task group 인스턴스 패치, 인증 없는 원격 버전 체크까지 더해졌고요.

이미지3-1_0.1.5신규
이미지3-1_0.1.5신규2640×872 171 KB

[이미지 4. airflowctl dags next-execution <dag_id> 또는 bulk delete 실행]

빠르게 써보기

# 설치 (Python >=3.10, !=3.15 — 사실상 3.10~3.14)
pip install apache-airflow-ctl

# 로그인 — 자격증명 생략 시 username/password를 대화형으로 물어봄. 토큰은 키링 저장.
airflowctl auth login --api-url https://<your-airflow>/api

# 현재 환경/인증 상태 확인
airflowctl auth list-envs

# DAG run 트리거 (그룹은 dagrun이 아니라 dags, 트리거 바디 동반)
airflowctl dags trigger <dag_id>            # 정확한 바디 인자는 --help 확인

# DAG run 조회 (dag_id는 positional이 아닌 --dag-id 플래그; 생략 시 전체 DAG)
airflowctl dagrun list --dag-id <dag_id>

# (참고) DAG 자체 목록 — dags list(인자 없음) ↔ dagrun list(DAG run 목록)는 다른 그룹
airflowctl dags list

# 헤드리스/CI: JWT 토큰만 출력해 파이프라인에 주입
airflowctl auth token

명령 옵션은 버전마다 늘어나고 있으니 airflowctl <command> --help로 확인하는 게 가장 정확합니다. 명령 상당수는 API operation 매핑에서 자동 생성되는 구조라, API가 늘면 명령도 같이 따라옵니다.

어디까지 왔나 (0.1.0 → 0.1.5)

image
image2612×540 63 KB

[이미지 5. 안정화 → 기능 전진 전환]

릴리스 흐름을 보면 지금 어느 단계인지가 잘 드러납니다.

  • 0.1.0 (2025-11) — 최초 릴리스. 키링 통합, API 기반 기본 명령.

  • 0.1.2 (2026-02) — XCom 명령, 다중 CLI 환경 관리(auth list-envs), 키링 관련 버그 대거 수정.

  • 0.1.3 (2026-03) — auth token(JWT 출력), 헤드리스 환경 지원, import 시 기존 키 처리 옵션, 재시도 메커니즘.

  • 0.1.4 (2026-04) — Python 3.14 지원, plugins 명령, 자동 생성 명령용 도움말 정비, 경로 탐색(path traversal) 취약점 차단 등 보안 수정.

  • 0.1.5 (2026-05) — Dag Next Execution·Bulk Delete·Rerun Latest Version 등 신규 명령, 커서 기반 페이지네이션·AIP-103 등 API 표면 확장, positional 인자 정리.

요점: 0.1.0~0.1.4는 인증·키링·종료 코드·헤드리스 같은 운영 기본기를 다지는 안정화기였습니다. 그리고 0.1.5에서 다시 기능 전진으로 방향이 바뀌었어요 — 신규 명령과 API 확장이 함께 들어왔고, positional 인자도 dev-list 합의로 형태가 수렴되는 중이라 CLI 인터페이스가 점점 굳어가는 신호입니다. (그래도 버전은 아직 0.1.x라는 점은 감안하세요. 오늘 기준 최신은 0.1.5입니다.)

언제 쓰면 좋고, 뭘 조심할까

잘 맞는 경우

  • CI/CD나 운영 자동화에서 DB 자격증명을 뿌리지 않고 RBAC·감사가 적용된 채 Airflow를 원격 조작하고 싶을 때

  • 멀티테넌트/팀 단위 운영 (team_name, team_id 인자가 들어와 있습니다)

  • 감사·보안 요건이 빡센 조직

주의할 점

  • 0.1.x 안정화 진행 중 → 자동화에 박기 전에 종료 코드와 인증 흐름을 본인 환경(특히 헤드리스 CI)에서 검증 권장

  • 0.1.5의 positional 인자 변경 주의 — 필수 파라미터가 --flag에서 위치 인자로 바뀌었습니다. 기존에 필수 인자를 --flag 형태로 넘기던 스크립트가 깨질 수 있으니 업그레이드 전 호출 형태를 점검하세요.

  • REST API가 노출돼 있어야 동작 → API 미오픈 환경에선 애초에 불가

  • 이름이 같은 kaxil/airflowctl(로컬 venv 기반 프로젝트 관리 도구)과는 완전히 다른 별개 프로젝트입니다. 헷갈리지 마세요.

혹시 이미 사내 CI에서 airflow CLI를 쓰고 계신 분들, DB 직결 → API 경유로 옮기면서 걸렸던 부분(토큰 주입, 종료 코드, RBAC 권한 매핑 등) 있으셨나요? 경험 공유 환영합니다 :raising_hands:

참고