Airflow 명령줄 인터페이스 액세스

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Apache Airflow에는 DAG 트리거 및 관리, DAG 실행 및 태스크 정보 가져오기, 연결 및 사용자 추가와 삭제 등의 작업을 수행하는 데 사용할 수 있는 명령줄 인터페이스(CLI)가 있습니다.

지원되는 Airflow CLI 명령어

Airflow는 Airflow 문서에 설명된 Airflow CLI 구문을 사용합니다.

Cloud Composer 3은 다음 Airflow CLI 명령어를 지원합니다.

  • (Airflow 2 및 3) gcloud composer environments run 명령어는 환경의 Airflow CLI 명령어를 실행합니다. 일부 명령은 차단되어 실행할 수 없습니다. 지원되는 Airflow CLI 명령어 목록은 명령어 참조를 확인하세요.

  • (Airflow 3) airflowctl 명령줄 도구는 Airflow CLI 명령어의 하위 집합을 지원하고 Airflow REST API를 사용하여 실행합니다. airflowctl에서 사용할 수 있는 모든 명령어는 Cloud Composer에서 지원됩니다. 사용자의 Airflow 계정에 특정 명령어를 실행할 수 있는 Airflow 역할이 있는지 확인합니다.

시작하기 전에

Google Cloud CLI를 통해 Airflow CLI 명령어를 실행하는 경우:

  • Cloud Composer에서 Google Cloud CLI를 사용하고 Airflow CLI 명령어를 실행할 수 있는 권한이 Google 계정에 있어야 합니다.

  • Google Cloud CLI를 통해 실행되는 Airflow CLI 명령어는 environments.executeAirflowCommand 할당량을 사용합니다.

airflowctl 명령줄 도구를 통해 Airflow CLI 명령어를 실행하는 경우 (Airflow 3):

gcloud CLI로 Airflow CLI 명령어 실행

환경에서 Airflow CLI 명령어를 실행하려면 gcloud CLI를 사용하세요.

gcloud composer environments run ENVIRONMENT_NAME \
    --location LOCATION \
    SUBCOMMAND \
    -- SUBCOMMAND_ARGUMENTS

다음을 바꿉니다.

  • ENVIRONMENT_NAME: 환경의 이름입니다.
  • LOCATION: 환경이 위치한 리전
  • SUBCOMMAND: 지원되는 Airflow CLI 명령어 중 하나입니다.
  • SUBCOMMAND_ARGUMENTS를 Airflow CLI 명령어의 인수로 바꿉니다.

하위 명령어 인수 구분 기호

지정된 Airflow CLI 명령어의 인수를 --로 구분합니다.

  • 복합 CLI 명령어를 하위 명령어로 지정합니다.
  • -- 구분 기호 뒤에 복합 명령어의 인수를 하위 명령어 인수로 지정합니다.

예:

gcloud composer environments run example-environment \
    dags list -- --output=json

기본 위치

대부분 gcloud composer 명령어에는 위치가 필요합니다. --location 플래그로 위치를 지정하거나 기본 위치를 설정할 수 있습니다.

예를 들어 Cloud Composer 환경에서 ID가 5077인 sample_quickstart DAG를 트리거하려면 다음을 실행합니다.

gcloud composer environments run example-environment \
    --location us-central1 dags trigger -- sample_quickstart \
    --run-id=5077

airflowctl로 Airflow CLI 명령어 실행

airflowctl 명령줄 도구는 Airflow CLI 명령어를 실행하기 위해 Airflow에서 제공하는 명령줄 유틸리티입니다. Airflow CLI 명령어의 하위 집합을 지원하고 Airflow REST API를 사용하여 실행합니다. airflowctl에서 사용할 수 있는 모든 명령어는 Cloud Composer에서 지원됩니다.

Cloud Composer에서 airflowctl를 사용한 승인 및 인증은 다음과 같이 작동합니다.

  • airflowctl는 Airflow REST API를 사용하므로 Google 계정 또는 서비스 계정과 연결된 Airflow 사용자 계정에 명령어를 실행할 수 있는 충분한 권한이 있는 Airflow 역할이 있는지 확인합니다. 예를 들어 일부 명령어는 Admin 역할이 있는 Airflow 사용자만 실행할 수 있습니다.

  • airflowctl에서 사용하는 API 토큰은 gcloud auth 명령어로 제공됩니다. 기본적으로 토큰의 만료 기간은 1시간입니다. 이 명령어에 제공된 --lifetime 인수를 사용하여 변경할 수 있습니다.

airflowctl로 인증하려면 다음 명령어를 실행합니다.

airflowctl auth login \
  --api-url WEB_SERVER_URL \
  --api-token $(gcloud auth print-access-token)

다음을 바꿉니다.

예:

airflowctl auth login \
  --api-url https://example-dot-us-central1.composer.googleusercontent.com \
  --api-token $(gcloud auth print-access-token)

airflowctl로 인증한 후 Airflow CLI 명령어를 실행할 수 있습니다.

airflowctl dags list

Cloud Composer API를 통해 Airflow CLI 명령어 실행

Cloud Composer 3에서는 Cloud Composer API를 통해 Airflow CLI 명령어를 실행할 수 있습니다.

명령어 실행

environments.executeAirflowCommand API 요청을 생성합니다.

{
  "environment": "projects/PROJECT_ID/locations/LOCATION/environments/ENVIRONMENT_NAME",
  "command": "AIRFLOW_COMMAND",
  "subcommand": "AIRFLOW_SUBCOMMAND",
  "parameters": [
    "SUBCOMMAND_PARAMETER"
  ]
}

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다.
  • LOCATION: 환경이 위치한 리전입니다.
  • ENVIRONMENT_NAME: 환경의 이름입니다.
  • AIRFLOW_COMMAND: 실행하려는 Airflow CLI 명령어입니다(예: dags).
  • AIRFLOW_SUBCOMMAND: 실행하려는 Airflow CLI 명령어의 하위 명령어입니다(예: list).
  • (선택사항) SUBCOMMAND_PARAMETER: 하위 명령어의 매개변수입니다. 매개변수를 두 개 이상 사용하려면 목록에 항목을 더 추가합니다.

예를 들면 다음과 같습니다.

// POST https://composer.googleapis.com/v1/{environment=projects/*/locations/*/environments/*}:executeAirflowCommand
{
  "environment": "projects/example-project/locations/us-central1/environments/example-environment",
  "command": "dags",
  "subcommand": "list",
  "parameters": [
    "-o json",
    "--verbose"
  ]
}

Poll 명령어 상태

Cloud Composer API를 통해 Airflow CLI 명령어를 실행한 후 PollAirflowCommand 요청을 전송하고 오류 및 상태 코드에 대해 exitInfo의 필드를 검사하여 명령어가 성공적으로 완료되었는지 확인합니다. output 필드에는 로그 줄이 포함됩니다.

명령어 실행 상태와 로그를 가져오려면 ExecuteAirflowCommandRequest에서 반환한 executionId, pod, podNamespace 값을 제공합니다.

예:

// POST https://composer.googleapis.com/v1/{environment=projects/*/locations/*/environments/*}:pollAirflowCommand
{
  "executionId": "a117da94-355d-4ad4-839e-ac39ccb0bf48",
  "pod": "airflow-webserver-66d96b858f-tn96b",
  "podNamespace": "airflow-2-10-2-build-13-226523e4",
  "nextLineNumber": 1
}

다음 단계