Airflow API를 사용하는 새로운 방법! Apache Airflow CTL, aka airflowctl 0.1.0이 출시되었습니다. 안전하게 Apache Airflow 배포를 관리할 수 있는 새로운 방법입니다.
Airflow REST API 기반의 안전하고 감사 가능한 커맨드라인 인터페이스(CLI)인 airflowctl 0.1.0의 첫 번째 주요 릴리스를 발표하게 되어 매우 기쁩니다 — AIP-81 기반으로 개발되었습니다.
이번 릴리스는 CLI가 API를 통한 운영으로 전환되는 첫 걸음을 의미합니다. Airflow CLI는 이제 안전하고 감사 가능하며 원격 중심(remote-first) 운영을 지원하는 현대적인 방식으로 진화했습니다.
설치 및 자료
- PyPI: Client Challenge
- 릴리스 노트: https://airflow.apache.org/docs/apache-airflow-ctl/stable/release_notes.html
- 소스 코드: airflow/airflow-ctl at main · apache/airflow · GitHub
airflowctl이란?
airflowctl은 Airflow REST API와만 상호작용하는 새로운 CLI입니다.
직접 메타데이터 데이터베이스에 접근하지 않고도, 안전하고 감사 가능한 방식으로 Airflow 배포를 관리할 수 있습니다.
Airflow CLI와의 공존
Airflow CLI는 기존대로 유지되며, 주로 Airflow 컴포넌트 실행(airflow api-server, airflow scheduler)이나 메타데이터 데이터베이스 관리(airflow db init)용으로 사용됩니다.
반면 airflowctl은 API를 통해 Airflow 리소스를 관리하는 운영 명령(airflowctl dagrun trigger, airflowctl connection create 등)에 집중합니다.
명령어는 크게 두 가지로 나뉩니다:
- 원격(Remote) 명령: DAG, 연결, 변수 관리, DAG 실행 트리거 등 API를 통해 수행할 수 있는 작업. airflowctl에서 수행하며 앞으로 권장되는 방식입니다.
- 로컬/관리(Admin) 명령: Airflow 컴포넌트나 메타데이터 DB를 관리하는 명령. 기존 Airflow CLI에서 수행됩니다.
현재는 두 CLI 모두 원격 명령을 지원하지만, 향후 airflowctl이 기능 동등성을 확보하면 Airflow CLI에서 원격 명령은 점진적으로 제거될 예정입니다.
왜 airflowctl인가?
기존 Airflow CLI는 메타데이터 DB에 직접 연결되어 RBAC, 인증, API 로그를 우회했습니다.
편리하지만, 기업 환경에서 필요한 보안, 감사, 원격 관리 기능이 제한되었습니다.
airflowctl은 모든 명령을 Airflow REST API를 통해 처리함으로써 다음을 제공합니다:
- 인증 및 RBAC 적용
- 중앙 집중식 로깅과 감사 추적
- 키링(Keyring)을 통한 안전한 자격 증명 저장
- DB 접근 없이 원격 명령 실행
- Airflow UI 및 API 동작과 일관된 명령 수행
AIP-81: API를 통한 CLI 재구상
AIP-81(“Enhanced Security in CLI via Integration of API”)은 다음 목표를 정의했습니다:
“CLI는 Airflow REST API의 1급, 안전한 클라이언트여야 하며 — DB 권한을 가진 특권 액터가 되어서는 안 된다.”
airflowctl은 이 비전을 직접 구현한 결과물입니다.
핵심 설계 원칙:
- 모든 원격 명령은 REST API를 사용
- RBAC와 인증을 API 레이어에서 일관되게 처리
- 플러그형 인증 지원(기본 인증, OAuth, 토큰 등)
- 시스템 키링을 통한 안전한 자격 증명 저장
- Airflow 발전에 따라 새로운 API 엔드포인트로 확장 가능
시작하기
pip install apache-airflow-ctl
설치 후, CLI를 Airflow 인스턴스에 연결합니다:
airflowctl auth login --url http://localhost:8080 --username admin --password admin
- 비밀번호는 기본적으로 터미널에 표시되지 않고 안전하게 입력할 수 있습니다.
--password옵션만 사용하면, 입력 시 비밀번호를 묻는 인터랙티브 모드가 실행됩니다.
주요 명령어
airflowctl 0.1.0에서 API 기반으로 안전하게 수행할 수 있는 주요 명령어:
Assets
Config
Connections
DAG Runs
Variables
모든 명령어는 Airflow REST API를 통해 수행되어 보안, 로그 기록, RBAC 제어가 보장됩니다.
핵심 보안 기능
키링 통합
- 더 이상 토큰이나 비밀번호를 평문으로 저장하지 않음
- OS 수준 키링(macOS Keychain, Windows Credential Manager, Linux Secret Service)을 사용해 안전하게 인증 정보 저장 및 조회
RBAC(Role-Based Access Control)
- 모든 명령은 API를 통해 Airflow의 RBAC 시스템으로 권한 검증
- 웹 UI와 API 클라이언트와 동일한 권한 관리
감사 및 추적
- 모든 CLI 명령은 API 로그를 생성
- 표준 감사 메커니즘으로 추적 가능
- 기존 CLI와 보안 모델 간 격차 해소
향후 로드맵
airflowctl 0.1.0은 시작 단계입니다.
향후 목표:
- API 커버리지 완전성 확보
- 라이브 로그 스트리밍
- 워커 관리
- 원격 디버깅
- 기존 CLI 명령 점진적 폐지
점진적으로 기존 Airflow CLI의 원격 명령은 API 기반 명령과 기능 동등성이 확보되면 폐지될 예정입니다.
마이그레이션
마이그레이션 과정:
- 명령어 매핑
- 인증 방식 업데이트
- 자동화 워크플로 테스트
airflowctl은 기존 CLI 구문과 유사하므로, 대부분 워크플로는 인증 및 설정 조정 정도만 필요합니다.
| 이전 | 이후 |
|---|---|
 |
 |
 |
 |
커뮤니티 & 감사
이번 릴리스는 Apache Airflow 커뮤니티의 폭넓은 협업으로 이루어졌습니다.
AIP-81, Airflow REST API, 인증, airflowctl 구현에 기여한 모든 분께 감사드립니다.
주요 기여자
Amar Prakash Pandey, Amogh Desai, Aritra Basu, Aryan Khurana, ayush3singh, Brent Bovenzi, Brunda10, Bugra Ozturk, Daniel Standish, D. Ferruzzi, Deji Ibrahim, Elad Kalif, Ephraim Anierobi, GPK, Guan Ming(Wesley) Chiu, Hussein Awala, Jake Roach, Jarek Potiuk, Jed Cunningham, Jens Scheffler, Jaejun Lee, Kalyan R, Karthikeyan Singaravelan, Kaxil Naik, Kevin Yang, Kiruban Kamaraj, LI,JHE-CHEN, Pierre Jeambrun, Pratiksha, Sam Wheating, Tzu-ping Chung, Valentyn, Vincent, Wei Lee, Yeonguk, Yunchi Pang, Zhen-Lun (Kevin) Hong
요약
airflowctl 0.1.0을 통해 Airflow CLI는 이제:
| 이전 | 이후 |
|---|---|
| DB 직접 접근 | API 기반 보안 |
| RBAC/감사 없음 | 중앙 집중식 인증 & 로깅 |
| 일관성 없는 동작 | 통합 CLI + API 경험 |
| 수동 비밀 관리 | 키링 보안 인증 |
보안 우선, API 항상, CLI 재구상
airflowctl은 Airflow 차세대 운영 플랫폼을 위한 통합, API 우선 CLI의 기반을 마련합니다.
본 글은 Apache Airflow 블로그 글을 GPT 모델을 활용하여 번역한 내용입니다. 따라서 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다.
관심있는 내용이시라면 원문도 함께 참고해주세요! Blog | Apache Airflow
읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시면 감사드리겠습니다.