Cloud Composer 1 はメンテナンス後モードです。Google は、Airflow の新しいバージョン、バグの修正、セキュリティアップデートなど、Cloud Composer 1 への今後のアップデートはリリースしません。 Cloud Composer 2 への移行の計画をおすすめします。

Composer ローカル開発 CLI ツールを使用してローカルの Airflow 環境を実行する

Cloud Composer 1 | Cloud Composer 2

ここでは、Composer ローカル開発 CLI ツールを使用して、ローカルの Airflow 環境を作成、構成、実行する方法について説明します。

Composer ローカル開発 CLI ツールの概要

Composer ローカル開発 CLI ツールは、Airflow 環境をローカルで実行することにより、Cloud Composer 向けの Apache Airflow DAG 開発を合理化します。このローカルの Airflow 環境では、特定の Cloud Composer バージョンのイメージが使用されます。

既存の Cloud Composer 環境に基づいてローカルの Airflow 環境を作成できます。この場合、ローカルの Airflow 環境はインストールされている PyPI パッケージと環境変数名のリストを Cloud Composer 環境から取得します。

このローカルの Airflow 環境は、テストや開発を目的として使用できます。たとえば、新しい DAG コード、PyPI パッケージ、Airflow 構成オプションをテストするなどです。

始める前に

Composer ローカル開発 CLI ツールは、composer-dev create コマンドを実行するディレクトリにローカルの Airflow 環境を作成します。後でローカルの Airflow 環境にアクセスするには、最初にローカル環境を作成したパスでツールコマンドを実行します。ローカル環境用のデータはすべて、ローカル環境を作成したパスのサブディレクトリ ./composer/<local_environment_name> に保存されます。
コンピュータには、Cloud Composer イメージを保存するのに十分なディスク容量が必要です。Composer ローカル開発 CLI ツールは、Cloud Composer のバージョンごとに 1 つのイメージファイルを保存します。たとえば、異なる Cloud Composer バージョンを持つ 2 つのローカル Airflow 環境がある場合、Composer ローカル開発 CLI ツールは 2 つの Cloud Composer イメージを保存します。
Composer ローカル開発 CLI ツールの出力は色付きです。NO_COLOR=1 の変数 NO_COLOR=1 composer-dev <other commands> を使用することで、色付きの出力を無効にできます。
ローカル環境が 1 つしかない場合は、run-airflow-cmd を除くすべての composer-dev コマンドでローカル環境の名前を省略できます。
Composer ローカル開発 CLI ツールの依存関係をインストールします。
- Python バージョン 3.7～3.10（pip を使用）
- Google Cloud CLI
Docker をインストールします。Docker がローカルシステムにインストールされ、実行されている必要があります。Docker が実行されていることを確認するには、docker ps などの任意の Docker CLI コマンドを実行します。

認証情報の構成

アプリケーションのデフォルト認証情報に使用する新しいユーザー認証情報を取得します（まだ行っていない場合）。

gcloud auth application-default login

Google アカウントを使用して gcloud CLI にログインします。

gcloud auth login

Composer ローカル開発 CLI ツールと DAG によって行われる API 呼び出しはすべて、gcloud CLI で使用するアカウントから実行されます。たとえば、ローカル Airflow 環境の DAG が Cloud Storage バケットの内容を読み取る場合、このアカウントにはバケットにアクセスするための権限が必要です。この点は、環境のサービスアカウントが呼び出しを行う Cloud Composer 環境とは異なります。

Composer ローカル開発 CLI ツールをインストールする

Composer ローカル開発 CLI リポジトリのクローンを作成します。

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

クローン作製されたリポジトリの最上位ディレクトリで、次のコマンドを実行します。

pip install .

pip 構成によっては、ツールをインストールするパスが PATH 変数に含まれていない場合があります。その場合は、pip によって警告メッセージが表示されます。この警告メッセージの情報をもとに、このディレクトリをオペレーティングシステムの PATH 変数に追加できます。

特定の Cloud Composer バージョンを使用してローカルの Airflow 環境を作成する

使用可能な Cloud Composer のバージョンを一覧表示するには、次のコマンドを実行します。

composer-dev list-available-versions --include-past-releases --limit 10

デフォルトのパラメータでローカルの Airflow 環境を作成するには、次のコマンドを実行します。

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

他のパラメータ:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

次のように置き換えます。

IMAGE_VERSION は、Cloud Composer イメージの名前に置き換えます。
PROJECT_ID は、プロジェクト ID に置き換えます。
WEB_SERVER_PORT は、Airflow ウェブサーバーがリッスンするポートに置き換えます。
LOCAL_DAGS_PATH は、DAG ファイルが配置されているローカルディレクトリへのパスに置き換えます。
LOCAL_ENVIRONMENT_NAME は、このローカル Airflow 環境の名前に置き換えます。

例:

composer-dev create \
  --from-image-version composer-2.8.0-airflow-2.7.3 \
  example-local-environment

Cloud Composer 環境からローカルの Airflow 環境を作成する

次の情報のみが Cloud Composer 環境から取得されます。

イメージのバージョン（環境で使用されている Cloud Composer と Airflow のバージョン）。
使用する環境にインストールされているカスタム PyPI パッケージのリスト。
使用する環境に設定された環境変数の名前のコメント化されたリスト。

重要: Cloud Composer では、環境変数の値はコピーされません。必要に応じて手動で構成ファイルの環境変数のコメント化を解除し、値を設定してください。

環境からのその他の情報や構成パラメータ（DAG ファイル、DAG 実行履歴、Airflow 変数、接続など）は Cloud Composer 環境からコピーされません。

既存の Cloud Composer 環境からローカルの Airflow 環境を作成するには、次のようにします。

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH

次のように置き換えます。

LOCAL_ENVIRONMENT_NAME は、ローカル Airflow 環境の名前に置き換えます。
ENVIRONMENT_NAME は、Cloud Composer 環境の名前に置き換えます。
LOCATION は、Cloud Composer 環境が配置されているリージョンに置き換えます。
PROJECT_ID は、プロジェクト ID に置き換えます。
WEB_SERVER_PORT は、ローカル Airflow ウェブサーバー用のポートに置き換えます。
LOCAL_DAGS_PATH は、DAG が配置されているローカルディレクトリへのパスに置き換えます。

例:

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

ローカルの Airflow 環境を起動する

ローカルの Airflow 環境を起動するには、次のコマンドを実行します。

composer-dev start LOCAL_ENVIRONMENT_NAME

次のように置き換えます。

LOCAL_ENVIRONMENT_NAME は、ローカル Airflow 環境の名前に置き換えます。

ローカルの Airflow 環境を停止または再起動する

ローカルの Airflow 環境を再起動すると、Composer ローカル開発 CLI ツールによって環境が実行されている Docker コンテナが再起動されます。Airflow コンポーネントはすべて停止され、再起動されます。その結果、再起動中に実行されたすべての DAG 実行は失敗としてマークされます。

停止したローカルの Airflow 環境を再起動または起動するには、次のコマンドを実行します。

composer-dev restart LOCAL_ENVIRONMENT_NAME

次のように置き換えます。

LOCAL_ENVIRONMENT_NAME は、ローカル Airflow 環境の名前に置き換えます。

ローカルの Airflow 環境を停止するには、次のコマンドを実行します。

composer-dev stop LOCAL_ENVIRONMENT_NAME

DAG を追加および更新する

DAG は、ローカルの Airflow 環境を作成したときに --dags-path パラメータで指定したディレクトリに保存されます。デフォルトでは、このディレクトリは ./composer/<local_environment_name>/dags です。環境で使用されているディレクトリは、describe コマンドを使用して取得できます。

DAG を追加および更新するには、このディレクトリでファイルを変更します。ローカルの Airflow 環境を再起動する必要はありません。

ローカル Airflow 環境のログを表示する

ローカルの Airflow 環境を実行している Docker コンテナの最近のログを表示できます。そうすることで、コンテナ関連のイベントをモニタリングし、PyPI パッケージのインストールに起因する依存関係の競合などのエラーを Airflow ログで確認できます。

ローカル Airflow 環境を実行している Docker コンテナのログを表示するには、次のコマンドを実行します。

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

ログストリームに従うには、--max-lines 引数を省略します。

composer-dev logs LOCAL_ENVIRONMENT_NAME

Airflow CLI コマンドを実行する

Airflow CLI コマンドは、ローカルの Airflow 環境で実行できます。

Airflow CLI コマンドは次のように実行します。

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

例:

composer-dev run-airflow-cmd example-local-environment dags list -o table

ローカルの Airflow 環境を構成する

Composer ローカル開発 CLI ツールは、ローカル Airflow 環境用の構成パラメータ（環境変数や PyPI パッケージの要件など）をローカル環境のディレクトリ（./composer/<local_environment_name>）に保存します。

構成はローカル Airflow 環境の起動時に適用されます。たとえば、競合する PyPI パッケージ要件を追加した場合、ローカル環境を起動したときに Composer ローカル開発 CLI ツールからエラーが報告されます。

Airflow 接続は、ローカル Airflow 環境のデータベースに格納されます。構成を行うには、Airflow CLI コマンドを実行するか、接続パラメータを環境変数に格納します。接続を作成して構成する方法の詳細については、Airflow ドキュメントの接続の管理をご覧ください。

ローカル Airflow 環境のリストとステータスを取得する

使用可能なすべてのローカル Airflow 環境を一覧表示し、そのステータスを表示するには:

composer-dev list

特定の環境を記述し、環境のイメージのバージョン、DAG パス、ウェブサーバー URL などの詳細を取得するには、次のコマンドを実行します。

composer-dev describe LOCAL_ENVIRONMENT_NAME

次のように置き換えます。

LOCAL_ENVIRONMENT_NAME は、ローカル Airflow 環境の名前に置き換えます。

ローカル Airflow 環境で使用されるイメージを一覧表示する

Composer ローカル開発 CLI ツールで使用されるすべてのイメージを一覧表示するには、次のコマンドを実行します。

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

プラグインをインストールしてデータを変更する

ローカル Airflow 環境のプラグインとデータは、ローカル環境のディレクトリ（./composer/<local_environment_name>/data と ./composer/<local_environment_name>/plugins）から取得されます。

/data ディレクトリと /plugins ディレクトリの内容を変更するには、該当するディレクトリ内のファイルを追加または削除します。Docker により、ファイルの変更内容がローカルの Airflow 環境に自動的に伝播されます。

Composer ローカル開発 CLI ツールを使って、データとプラグインに別個のディレクトリを指定することはできません。

環境変数を構成する

環境変数を構成するには、環境ディレクトリ ./composer/<local_environment_name>/variables.env にある variables.env ファイルを編集します。

variables.env ファイルには、環境変数ごとに 1 行ずつの Key-Value 定義が含まれている必要があります。Airflow 構成オプションを変更するには、AIRFLOW__SECTION__KEY 形式を使用します。使用可能な環境変数については、Airflow 構成リファレンスをご覧ください。

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

変更を適用するには、ローカルの Airflow 環境を再起動します。

PyPI パッケージをインストールまたは削除する

PyPI パッケージをインストールまたは削除するには、環境ディレクトリ ./composer/<local_environment_name>/requirements.txt 内の requirements.txt ファイルを変更します。

要件は PEP-508 で指定された形式に従う必要があります。各要件は、小文字で指定され、オプションの追加情報とバージョン指定子とともにパッケージ名で構成されます。

変更を適用するには、ローカルの Airflow 環境を再起動します。

別の Cloud Composer イメージに切り替える

任意の Cloud Composer イメージを Composer ローカル開発 CLI ツールで使用して、イメージを切り替えることができます。このアプローチは Cloud Composer 環境のアップグレードとは異なり、起動時にローカルの Airflow 環境の構成パラメータが適用されます。

たとえば、新しい Cloud Composer バージョンがリリースされたら、新しいバージョンを使用するように環境を切り替え、既存のローカルの Airflow 環境構成を維持できます。別の例として、特定の Cloud Composer バージョン内の別の Airflow バージョンに切り替えることもできます。

ローカル Airflow 環境で使用される環境のイメージを変更するには:

ローカル環境の構成ファイル ./composer/<local_environment_name>/config.json を編集します。
composer_image_version パラメータの値を変更します。使用可能な値を表示するには、利用可能な Cloud Composer のバージョンを一覧表示します。
変更を適用するには、ローカルの Airflow 環境を再起動します。

ローカルの Airflow 環境を削除する

注意: ログや構成など、環境から取得した必要なデータはすべて保存しておいてください。

ローカルの Airflow 環境を削除するには、次のコマンドを実行します。

composer-dev remove LOCAL_ENVIRONMENT_NAME

環境が実行されている場合は、--force フラグを追加して強制的に削除します。

Docker イメージを削除する

Composer ローカル開発 CLI ツールによってダウンロードしたすべてのイメージを削除するには、次のコマンドを実行します。

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

トラブルシューティング

このセクションでは、一般的な問題の解決策を説明します。

macOS でローカル環境を起動できない

Docker がアクセスできないディレクトリに composer-dev パッケージをインストールした場合、ローカル環境が起動しないことがあります。

たとえば、Python が /opt ディレクトリにインストールされている場合（MacOS で Homebrew のデフォルト構成を使用してインストールする場合など）、composer-dev パッケージも /opt ディレクトリにインストールされます。Docker は Apple のサンドボックスルールに準拠しているため、デフォルトでは /opt ディレクトリを使用できません。また、UI（設定 > [リソース] > [ファイル共有]）から追加することもできません。

この場合、Composer ローカル開発 CLI ツールによって、次の例のようなエラーメッセージが生成されます。

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

次のいずれかのソリューションを使用できます。

Python または composer-dev パッケージを別のディレクトリにインストールして、Docker がパッケージにアクセスできるようにします。
~/Library/Group\ Containers/group.com.docker/settings.json ファイルを手動で編集して、/opt を filesharingDirectories に追加します。

Composer ローカル開発 CLI ツールを使用してローカルの Airflow 環境を実行する

Composer ローカル開発 CLI ツールの概要

始める前に

認証情報の構成

Composer ローカル開発 CLI ツールをインストールする

特定の Cloud Composer バージョンを使用してローカルの Airflow 環境を作成する

Cloud Composer 環境からローカルの Airflow 環境を作成する

ローカルの Airflow 環境を起動する

ローカルの Airflow 環境を停止または再起動する

DAG を追加および更新する

ローカル Airflow 環境のログを表示する

Airflow CLI コマンドを実行する

ローカルの Airflow 環境を構成する

ローカル Airflow 環境のリストとステータスを取得する

ローカル Airflow 環境で使用されるイメージを一覧表示する

プラグインをインストールしてデータを変更する

環境変数を構成する

PyPI パッケージをインストールまたは削除する

別の Cloud Composer イメージに切り替える

ローカルの Airflow 環境を削除する

Docker イメージを削除する

トラブルシューティング

macOS でローカル環境を起動できない

次のステップ