Airflow コマンドライン インターフェースにアクセスする

マネージド Airflow（第 3 世代） | マネージド Airflow（第 2 世代） | マネージド Airflow（レガシー第 1 世代）

Apache Airflow には、DAG のトリガーと管理、DAG 実行とタスクに関する情報の取得、接続とユーザーの追加と削除など、タスクの実行に使用できるコマンドライン インターフェース（CLI）があります。

サポートされている Airflow CLI コマンド

Airflow では、 Airflow ドキュメントに記載されているAirflow CLI 構文を使用します。

マネージド Airflow（第 3 世代）では、次の Airflow CLI コマンドがサポートされています。

• （Airflow 2 と 3） gcloud composer environments run コマンド は、環境の Airflow CLI コマンドを実行します。一部のコマンドはブロックされており、実行できません。サポートされている Airflow CLI コマンドの一覧については、 コマンドのリファレンスをご覧ください。

• （Airflow 3） airflowctl コマンドライン ツールは、Airflow CLI コマンドの サブセットをサポートし、Airflow REST API を使用して実行します。 airflowctl で使用可能なすべてのコマンドは、Managed Airflow でサポートされています。ユーザーの Airflow アカウントに、 特定のコマンドを実行できる Airflow ロールがあることを確認してください。

始める前に

Google Cloud CLI を使用して Airflow CLI コマンドを実行するには:

• Google アカウントに、Managed Airflow で Google Cloud CLI を使用して Airflow CLI コマンドを実行する権限が必要です。

  注意: composer.environments.executeairflowcommand 権限を持つユーザーは、環境のサービス アカウントに代わって、Airflow コンポーネントで使用可能な Python コードを実行できます。詳細については、アクセス制御をご覧ください。

• Google Cloud CLI を使用して実行される Airflow CLI コマンドは、 environments.executeAirflowCommand 割り当てを消費します。

  重要: 多数の DAG をトリガーする場合は、Airflow REST API を使用するか、Airflow 3 の airflowctl コマンドライン ツールを使用することをおすすめします。Google Cloud CLI を使用して DAG をトリガーすると、環境が割り当て上限に達し、Airflow CLI コマンドが実行されなくなる可能性があります。

airflowctl コマンドライン ツール（Airflow 3）を使用して Airflow CLI コマンドを実行するには:

• Google アカウントに composer.environments.get 権限が必要です。これは、 マネージド Airflow 環境を表示できるロールによって提供されます。 airflowctl コマンドライン ツールでは、Airflow CLI コマンドを実行するための 権限は必要ありません。

• airflowctl を使用して実行される Airflow CLI コマンドは、 environments.executeAirflowCommand 割り当てを消費しません。

注: マネージド Airflow（第 3 世代）では、kubectl を使用して Airflow CLI コマンドを実行することはできません。この方法は非推奨となり、2.4.0 より前の Managed Airflow バージョンでのみ必要です。

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 フラグを使用するか、 デフォルトの場所を設定します。

たとえば、Managed Airflow 環境で 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 で使用可能なすべてのコマンドは、Managed Airflow でサポートされています。

マネージド Airflow での airflowctl を使用した認可と認証は、次のように機能します。

• airflowctl は Airflow REST API を使用するため、Google アカウントまたはサービス アカウントに関連付けられた Airflow ユーザー アカウントに、コマンドを実行するのに十分な権限を持つ Airflow ロールがあることを確認してください。たとえば、一部のコマンドは、Admin ロールを持つ Airflow ユーザーのみが実行できます。

• airflowctl で使用される API トークンは、 gcloud auth application-default print-access-token コマンドで提供されます。 デフォルトでは、トークンの有効期間は 1 時間です。このコマンドに指定された --lifetime 引数を使用して変更できます。

airflowctl で認証するには、次のコマンドを実行します。

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

以下を置き換えます。

• WEB_SERVER_URL: Airflow ウェブサーバーの URL。この URL の末尾にスラッシュ（/）がないことを確認してください。

例:

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

airflowctl で認証したら、Airflow CLI コマンドを実行できます。

airflowctl dags list

Cloud Composer API を使用して Airflow CLI コマンドを実行する

マネージド Airflow（第 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"
  ]
}

ポーリング コマンドのステータス

Cloud Composer API を使用して Airflow CLI コマンドを実行した後、PollAirflowCommand リクエストを発行し、エラーとステータス コード用の　exitInfo のフィールドを調べて、コマンドが正常に完了したかどうかを確認します。output フィールドにはログ行が含まれます。

注: StopAirflowCommand を使用してコマンドの実行を停止することもできます。

コマンドの実行ステータスを取得してログを取得するには、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
}

次のステップ

• Airflow UI にアクセスする
• アクセス制御（Airflow CLI）