Astro CLI 스킬
이 스킬을 사용해야 할 때
- Astro/Airflow 프로젝트를 초기화, 구성, 검증할 때.
- 로컬 Airflow 환경(Docker 또는 Standalone 모드)을 관리할 때.
- Astronomer 클라우드 배포, 워크스페이스, 배포와 상호작용할 때.
astro api airflow래퍼를 통해 Airflow REST API를 호출할 때.- 로그를 보거나 환경 변수를 관리하여 프로덕션 배포를 문제 해결할 때.
사용하지 말아야 할 때
- Astronomer CLI 작업과 관련 없는 일반 Apache Airflow DAG을 작성할 때.
사전 요구 사항
- Astro CLI (
astro)가 설치되어 있어야 합니다. - Docker가 실행 중이어야 합니다 (표준 로컬 개발용).
uv가 설치되어 있어야 합니다 (Standalone 로컬 개발용).
핵심 프로세스
- 클라우드 API 또는 배포 명령어를 실행하기 전에
astro login을 사용하여 인증합니다. - 로컬 개발을 위해
astro dev start를 사용하여 Airflow를 시작합니다. - 로컬 및 클라우드 환경 모두에 대한 인증된 API 요청을 위해
astro api airflow를 사용합니다.
단계별 워크플로우
프로젝트 설정 및 구성
- 프로젝트 초기화:
astro dev init - DAG 로컬 검증:
astro dev parse - 연결/변수 내보내기:
astro dev object export --connections --variables - 연결/변수 가져오기:
astro dev object import --connections --variables --file <경로>
로컬 환경 관리
- 시작 (Docker):
astro dev start - 시작 (Standalone):
astro dev start --standalone - 중지/종료:
astro dev stop/astro dev kill(kill은 볼륨/venv를 제거합니다) - 로컬 로그 보기:
astro dev logs --scheduler(또는--webserver,--workers) - Airflow CLI 실행:
astro dev run dags list - 프록시 상태 확인:
astro dev proxy status(멀티 프로젝트 라우팅용)
로컬 개발을 위한 Astro CLI 명령어
- 탭 완성 가져오기:
astro completion <셸>(Astro CLI 명령어에 대한 탭 완성 스크립트) - 레지스트리 정보 가져오기:
astro api registry(Airflow 레지스트리 API에서 정보 가져오기) - 스케줄러에서 bash 실행:
astro dev bash(스케줄러 컨테이너에 들어가 bash 명령어 실행) - 모든 컨테이너 제거:
astro dev kill(메타데이터베이스, 연결을 포함한 모든 컨테이너 제거) - 스트림/로그 가져오기:
astro dev logs(로그 가져오기 -s / -d / -t / -a, -f는 스트리밍) - 가져오기 오류 확인:
astro dev parse(가져오기 오류 확인) - 컨테이너에서 테스트 실행:
astro dev pytest(/tests의 테스트를 컨테이너에서 실행) - Airflow CLI 명령어 실행:
astro dev run(모든 Airflow CLI 명령어 실행 가능!) - DAG 강제 재파싱:
astro dev run dags reserialize(새 DAG을 포함한 모든 DAG의 강제 재파싱) - 클라우드 연결로 로컬 시작:
astro dev start --deployment-id [배포-id](Astro 고객이 배포와 동일한 Airflow 연결로 로컬에서 시작)
클라우드 배포 관리
- 워크스페이스 전환:
astro workspace switch <워크스페이스_ID> - 배포 목록/검사:
astro deployment list/astro deployment inspect <배포_ID> - 배포 생성:
astro deployment create --label <이름> --executor celery - 코드 배포 (전체):
astro deploy <배포_ID> - DAG만 배포:
astro deploy <배포_ID> --dags(dag-deploy-enabled필요) - 변수 관리:
astro deployment variable create --deployment-id <ID> --key <키> --value <값> --secret
클라우드 배포 문제 해결
- 배포 로그 보기:
astro deployment logs <배포_ID> --error - 구성 요소별 로그 필터링:
astro deployment logs <ID> --scheduler(또는--workers,--triggerer) - 로그 검색:
astro deployment logs <ID> --keyword "ImportError"
Astro CLI를 통한 Airflow REST API 호출 실행
astro api airflow 명령어는 현재 컨텍스트에 대한 인증을 자동으로 처리합니다.
예시:
- DAG 목록:
astro api airflow get_dags - DAG 세부 정보 가져오기:
astro api airflow get_dag -p dag_id=<dag_id> - DAG 실행 트리거:
astro api airflow trigger_dag_run -p dag_id=<dag_id> -F conf[key]=value - 태스크 인스턴스 목록:
astro api airflow get_task_instances -p dag_id=<dag_id> -p dag_run_id=~ - jq로 필터링:
astro api airflow get_dags -q '.dags[].dag_id'
일반적인 실수
- 인증 누락: 클라우드 작업 전에
astro login을 실행하지 않는 경우. - 컨텍스트 불일치: 잘못된 워크스페이스나 배포에서 명령어를 실행하는 경우. 항상
astro workspace list또는astro deployment list를 확인하세요. - Standalone 버전 고정: Standalone 모드는 Airflow 3.x/Runtime 13.x+가 필요합니다.
- 대화형 명령어 중단: 적절한 플래그 없이 비대화형 환경에서
astro login과 같은 대화형 명령어를 실행하지 마세요.
관련 스킬
- astronomer-docs: llms.txt 컨텍스트를 사용하여 Astronomer 문서를 읽고 탐색합니다.
- apache-airflow-api: Apache Airflow Stable REST API 쿼리를 실행하고, DAG, 백필, 연결, 변수, 자산을 관리합니다.
- Astro 로컬 환경 관리
- Astro 배포 문제 해결