Cortex Code CLI에서 Apache Airflow™ 사용하기¶

Cortex Code는 Apache Airflow™를 기본적으로 지원하여Airflow 배포 전반에 걸쳐 DAGs를 관리하고, 실패를 디버깅하고, 파이프라인을 작성하고, 데이터를 분석하고, 계보를 추적할 수 있는 자연어 인터페이스를 제공합니다.

기능¶


기능	설명	프롬프트 예제
파이프라인 모니터링	상태 확인, DAG 검사, 연결 및 변수 가시성, 스케줄링 제어	“내 Airflow 인스턴스의 정상 여부”
실행 관리	요청 시 DAGs 트리거, 결과 대기, 사용자 지정 구성 전달	“day_etl DAG 테스트 및 완료 시 알려주기”
실패 디버깅	영향 평가 및 수정 권장 사항을 통해 실행 상태, 작업 인스턴스, 로그에 대한 근본 원인 분석	“어젯밤에 my_pipeline이 실패한 이유”
DAG 작성	발견-계획-구현-유효성 검사-테스트 워크플로를 통해 기존 패턴, 연결, 공급자를 사용하여 DAG 생성 안내	“Snowflake에서 추출하고 매일 S3에 로드하는 DAG 생성”
데이터 분석	패턴 캐싱 및 개념 간 학습을 통한 웨어하우스 쿼리, 테이블 프로파일링, 최신성 검사	“이번 분기 활성 고객의 수”
데이터 계보	중요도 등급의 DAG 소스 코드를 통한 업스트림 원본 추적 및 다운스트림 영향 분석	“고객 테이블 스키마를 변경하면 중단되는 기능”
Airflow 3 마이그레이션	Ruff 규칙, 가져오기 수정 사항, 컨텍스트 키 대체, 메타데이터 액세스 패턴 업데이트를 통해 자동화된 코드 마이그레이션	“내 DAGs를 Airflow 2에서 Airflow 3으로 마이그레이션”
dbt 통합	구문 분석, 실행 및 프로필 구성이 포함된 Astronomer Cosmos를 통해 dbt Core 또는 Fusion 프로젝트를 Airflow DAGs로 실행	“Cosmos를 사용하여 Airflow에서 실행되도록 내 dbt 프로젝트 설정”
휴먼인더루프(Human-in-the-Loop)	DAGs의 승인 게이트, 양식 입력, 인간 주도 분기(Airflow 3.1 이상)	“배포 작업 전에 승인 단계 추가”
로컬 환경	Astro CLI를 사용하여 로컬 Airflow 환경 시작, 중지, 다시 시작, 문제 해결	“내 로컬 Airflow 환경 시작”

전제 조건¶

Cortex Code의 Airflow 통합에는 `uv <https://docs.astral.sh/uv/getting-started/installation/>`_가 필요합니다. ``uv``가 설치되지 않은 경우 ``cortex airflow``는 설치 링크와 함께 유용한 메시지를 제공합니다.

Airflow 통합 설정하기¶

Cortex Code로 Airflow 인스턴스를 관리하려면 먼저 연결을 구성해야 합니다. 이 작업은 환경 변수를 사용하거나 대화형 설정 명령으로 Cortex Code CLI 내에서 수행할 수 있습니다.

환경 변수 설정

다음과 같이 Cortex Code를 시작하기 전에 셸에서 필수 변수를 내보냅니다. 토큰 기반 인증 또는 사용자 이름 및 비밀번호 인증을 사용할 수 있습니다. 항상 동일한 Airflow 인스턴스를 사용하는 경우 매번 다시 입력할 필요가 없도록 셸 프로필(~/.bashrc 또는 ~/.zshrc)에 다음과 같은 코드를 포함합니다.

# Token auth
export AIRFLOW_API_URL=https://airflow.example.com
export AIRFLOW_AUTH_TOKEN=your-api-token

# Username/password auth
export AIRFLOW_API_URL=https://airflow.example.com
export AIRFLOW_USERNAME=your-username
export AIRFLOW_PASSWORD=your-password

대화형 설정

Cortex Code에서 ``/airflow``를 발행하여 전체 화면 UI를 통해 인스턴스를 관리합니다. 토큰 및 사용자 이름 또는 비밀번호 인증이 모두 지원됩니다.


명령	설명
`/airflow`	Airflow 인스턴스 관리(인스턴스 관리자 열기)
`/airflow show`	현재 구성 표시(시크릿은 마스킹됨)
`/airflow clear`	모든 구성 제거

``/airflow``는 여러 명명된 인스턴스를 지원합니다. 인스턴스 관리자를 사용하여 인스턴스를 추가하거나 전환하거나 제거합니다.

Airflow CLI 명령¶

아래 예제와 같이 ``cortex airflow``를 사용하여 터미널에서 Airflow 인스턴스와 상호 작용할 수 있습니다.

인스턴스 상태를 확인합니다.

cortex airflow health

모든 DAGs를 나열합니다.

cortex airflow dags list

특정 DAG에 대한 세부 정보를 가져옵니다.

cortex airflow dags get my_pipeline

DAG 소스 코드를 확인합니다.

cortex airflow dags source my_pipeline

DAG 실행을 트리거합니다.

cortex airflow runs trigger my_pipeline

DAG에 대한 최근 실행을 나열합니다.

cortex airflow runs list my_pipeline

특정 실행에 대한 작업 상태를 확인합니다.

cortex airflow tasks list my_pipeline <run_id>

DAG를 일시 중지하거나 일시 중지를 해제합니다.

cortex airflow dags pause my_pipeline
cortex airflow dags unpause my_pipeline

명령의 전체 목록을 확인하려면 ``cortex airflow –help``를 발행합니다.

문제 해결하기¶

연결 거부됨

증상: 연결 오류로 인해 Airflow 작업이 실패합니다.

해결책: 인스턴스 URL가 정확하고 Airflow API에 연결할 수 있는지 확인합니다. 현재 인스턴스 구성을 확인하고 상태 확인으로 연결을 테스트합니다.

인증 실패

증상: 작업이 401 또는 403 오류를 반환합니다.

해결책: 다음 단계를 시도해 봅니다.

토큰 또는 자격 증명이 올바른지 확인합니다.
토큰이 만료되었는지 확인하고 필요한 경우 다시 생성합니다.
사용자 및 역할에 Airflow의 API 액세스 권한이 있는지 확인합니다.

DAG를 찾을 수 없음

증상: 작업 보고서에서 DAG가 존재하지 않음을 보고합니다.

해결책: DAG 로딩을 방해할 수 있는 가져오기 또는 구문 분석 오류가 있는지 확인합니다. DAG ID가 정확히 일치하는지 확인합니다.

``uv``가 설치되지 않음

증상: ``cortex airflow``에 “cortex airflow에 uv가 필요함”이 표시됩니다.

해결책: `uv 사이트 <https://docs.astral.sh/uv/getting-started/installation/>`_에서 ``uv``를 설치합니다.