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

Python 依存関係をインストールする

Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3

このページでは、Cloud Composer 環境の Python パッケージをインストールする方法について説明します。

Cloud Composer イメージのプリインストール済み PyPI パッケージとカスタム PyPI パッケージについて

Cloud Composer イメージには、プリインストール済み PyPI パッケージとカスタム PyPI パッケージの両方が含まれています。

プリインストールされた PyPI パッケージは、環境の Cloud Composer イメージに含まれているパッケージです。各 Cloud Composer イメージには、ご使用の Airflow と Cloud Composer のバージョンに固有の PyPI パッケージが含まれています。
カスタム PyPI パッケージは、プリインストールされたパッケージに加えて、環境にインストールできるパッケージです。

Cloud Composer 環境の PyPI パッケージを管理するオプション

オプション	使用条件
PyPI からインストールする	環境にパッケージをインストールするデフォルトの方法
パブリック IP アドレスを持つリポジトリからインストールする。	パッケージが PyPI 以外のパッケージリポジトリでホストされている。このリポジトリにはパブリック IP アドレスがある
Artifact Registry リポジトリからインストールする	パッケージが Artifact Registry リポジトリでホストされている
プロジェクトのネットワーク内のリポジトリからインストールする	環境が公共のインターネットにアクセスできません。パッケージは、プロジェクトのネットワークのパッケージリポジトリでホストされています。
ローカルの Python ライブラリとしてインストールする	PyPI でパッケージが見つからないため、ライブラリに外部依存関係（`dist-packages` など）はありません。
プラグインをインストールする	このパッケージは、プラグイン固有の機能（Airflow ウェブインターフェースの変更など）を提供します。
PythonVirtualenvOperator	すべての Airflow ワーカーにパッケージをインストールしない、または、依存関係がプリインストールされているパッケージと競合する。パッケージが PyPI にあり、外部依存関係がありません。
KubernetesPodOperator と GKE オペレーター	`pip` からインストールできない外部依存関係（`dist-packages` など）、または内部の pip サーバー上にある外部依存関係が必要な場合。このオプションでは、より多くの設定とメンテナンスが必要になります。他のオプションが機能しない場合にのみ、これを考慮してください。

始める前に

環境の更新オペレーションをトリガーできるロールが必要です。また、環境のサービスアカウントには、更新オペレーションの実行に十分な権限を持つロールが必要です。詳しくは、アクセス制御をご覧ください。
ご使用の環境が VPC Service Controls の境界で保護されている場合に PyPI の依存関係をインストールするには、サービス境界によって保護されているサービスへのアクセス権とともに追加のユーザー ID を付与し、プライベート PyPI リポジトリに対するサポートを有効にする必要があります。
要件は PEP-508 で指定された形式に従う必要があります。各要件は、小文字で指定され、オプションの追加情報とバージョン指定子とともにパッケージ名で構成されます。
PyPI 依存関係の更新により、Artifact Registry に Docker イメージが生成されます。

警告: Cloud Composer によってビルドされたイメージは、Artifact Registry またはそのリポジトリ自体で変更または削除しないでください。独自のイメージをリポジトリにアップロードしないでください。代わりに、イメージ用に独自のリポジトリを作成して維持します（KubernetesPodOperator で使用されるイメージなど）。このリポジトリをご自身で削除しないでください。環境を削除すると、リポジトリは削除されます。
依存関係の競合が原因で更新が失敗した場合は、既存の依存関係内で環境が引き続き実行します。オペレーションが成功すると、DAG に新しくインストールされた Python 依存関係の使用を開始できます。
カスタムサービスアカウントでビルドを実行する場合は、選択したサービスアカウントで COMPOSER_AGENT_BUILD_SERVICE_ACCOUNT 環境変数をオーバーライドできます。このサービスアカウントは、Cloud Build ドキュメントに沿ってビルドを実行するように構成する必要があります。また、環境のサービスアカウントには iam.serviceAccounts.actAs 権限が必要です。
2024 年 4 月 29 日以降に Cloud Composer API が有効になっているプロジェクト。組織が constraints/cloudbuild.disableCreateDefaultServiceAccount ポリシーをオーバーライドしない限り、API を有効にしたときに、新しいプロジェクトは以前の Cloud Build サービスアカウントをプロビジョニングしません。Cloud Composer 環境にカスタム PyPI パッケージをインストールすると、デフォルトで Cloud Build が使用されるため、パッケージのインストールが失敗する可能性があります。デフォルトでは、代わりに環境のサービスアカウントが使用されるため、そのサービスアカウントにも、非公開パッケージへのアクセスに必要な追加の権限を付与してください。

PyPI パッケージのリストを表示する

環境のパッケージのリストを取得するには、いくつかの形式があります。

プリインストールされているパッケージを表示する

環境にプリインストールされているパッケージのリストを表示するには、環境の Cloud Composer イメージのパッケージの一覧表示をご覧ください。

すべてのパッケージを表示

環境内のすべてのパッケージ（プリインストールとカスタムの両方）を表示するには:

gcloud

次の gcloud CLI コマンドは、環境内の Airflow ワーカーの python -m pip list コマンドの結果を返します。 --tree 引数を使用すると、python -m pipdeptree --warn コマンドの結果を取得できます。

gcloud beta composer environments list-packages \
    ENVIRONMENT_NAME \
    --location LOCATION

以下のように置き換えます。

ENVIRONMENT_NAME を環境の名前にする。
LOCATION は、環境が配置されているリージョン。

カスタム PyPI パッケージを表示する

コンソール

Google Cloud Console で [環境] ページに移動します。

[環境] に移動
環境のリストで、ご利用の環境の名前をクリックします。[環境の詳細] ページが開きます。
[PyPI パッケージ] タブに移動します。

gcloud

gcloud composer environments describe ENVIRONMENT_NAME \
  --location LOCATION \
  --format="value(config.softwareConfig.pypiPackages)"

以下のように置き換えます。

ENVIRONMENT_NAME を環境の名前にする。
LOCATION は、環境が配置されているリージョン。

Cloud Composer 環境にカスタムパッケージをインストールする

このセクションでは、環境にカスタムパッケージをインストールするさまざまな方法について説明します。

PyPI からパッケージをインストールする

外部の依存関係がない場合や、プリインストールされているパッケージと競合しない場合は、Python パッケージインデックスからインストールできます。

環境の Python 依存関係を追加、更新、削除するには、次の手順を行います。

コンソール

Google Cloud Console で [環境] ページに移動します。

[環境] に移動
環境のリストで、ご利用の環境の名前をクリックします。[環境の詳細] ページが開きます。
[PyPI パッケージ] タブに移動します。
[編集] をクリックします。
[パッケージを追加] をクリックします。
[PyPI パッケージ] セクションで、オプションの追加情報とバージョン指定子とともにパッケージ名を指定します。

例:
- scikit-learn
- scipy、>=0.13.3
- nltk、[machine_learning]
[保存] をクリックします。

gcloud

gcloud CLI には、カスタムの PyPI パッケージを使用して作業するためのいくつかの引数があります。

--update-pypi-packages-from-file は、既存のカスタム PyPI パッケージをすべて指定されたパッケージに置き換えます。指定しないパッケージは削除されます。
--update-pypi-package は 1 つのパッケージを更新またはインストールします。
--remove-pypi-packages は、指定されたパッケージを削除します。
--clear-pypi-packages はパッケージをすべて削除します。

ファイルからの要件のインストール

requirements.txt ファイルには、個別の列に要件指定子が必要です。

例:

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

環境を更新し、--update-pypi-packages-from-file 引数に requirements.txt ファイルを指定します。

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-packages-from-file requirements.txt

以下のように置き換えます。

ENVIRONMENT_NAME を環境の名前にする。
LOCATION は、環境が配置されているリージョン。

1 つのパッケージのインストール

環境を更新し、--update-pypi-package 引数でパッケージ、バージョン、その他情報を指定します。

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-package PACKAGE_NAMEEXTRAS_AND_VERSION

以下のように置き換えます。

ENVIRONMENT_NAME を環境の名前にする。
LOCATION は、環境が配置されているリージョン。
PACKAGE_NAME はパッケージの名前に置き換えます。
EXTRAS_AND_VERSION は、オプションのバージョンと追加の指定子に置き換えます。バージョンとその他情報を省略するには、空の値を指定します。

例:

gcloud composer environments update example-environment \
    --location us-central1 \
    --update-pypi-package "scipy>=0.13.3"

パッケージの削除

環境を更新し、削除するパッケージを --remove-pypi-packages 引数で指定します。

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --remove-pypi-packages PACKAGE_NAMES

以下のように置き換えます。

ENVIRONMENT_NAME を環境の名前にする。
LOCATION は、環境が配置されているリージョン。
PACKAGE_NAMES は、パッケージのカンマ区切りのリストに置き換えます。

例:

gcloud composer environments update example-environment \
    --location us-central1 \
    --remove-pypi-packages scipy,scikit-learn

API

environments.patch API リクエストを作成します。

このリクエストで次のように操作します。

updateMask パラメータで、マスクを指定します。
- config.softwareConfig.pypiPackages マスクを使用して、既存のすべてのパッケージを指定されたパッケージに置き換えます。指定しないパッケージは削除されます。
- config.softwareConfig.envVariables.PACKAGE_NAME を使用して、特定のパッケージを追加または更新します。複数のパッケージを追加または更新するには、複数のマスクをカンマで区切って指定します。
リクエストの本文で、パッケージと、バージョンと追加情報の値を指定します。
```
{
  "config": {
    "softwareConfig": {
      "pypiPackages": {
        "PACKAGE_NAME": "EXTRAS_AND_VERSION"
      }
    }
  }
}
```
以下のように置き換えます。
- PACKAGE_NAME はパッケージの名前に置き換えます。
- EXTRAS_AND_VERSION は、オプションのバージョンと追加の指定子に置き換えます。バージョンとその他情報を省略するには、空の値を指定します。
- 複数のパッケージを追加するには、パッケージの追加エントリを pypiPackages に加えます。

例:

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.pypiPackages.EXAMPLE_PACKAGE,
// config.softwareConfig.pypiPackages.ANOTHER_PACKAGE
{
  "config": {
    "softwareConfig": {
      "pypiPackages": {
        "EXAMPLE_PACKAGE": "",
        "ANOTHER_PACKAGE": ">=1.10.3"
      }
    }
  }
}

Terraform

software_config ブロックの pypi_packages ブロックでパッケージを指定します。

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

以下のように置き換えます。

ENVIRONMENT_NAME を環境の名前にする。
LOCATION は、環境が配置されているリージョン。
PACKAGE_NAME はパッケージの名前に置き換えます。
EXTRAS_AND_VERSION は、オプションのバージョンと追加の指定子に置き換えます。バージョンとその他情報を省略するには、空の値を指定します。
複数のパッケージを追加するには、パッケージの追加エントリを pypi_packages に加えます。

例:

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "example-environment"
  region = "us-central1"

  config {

    software_config {
      pypi_packages = {
          scipy = ">=1.10.3"
          scikit-learn = ""
          nltk = "[machine_learning]"
      }
    }
  }
}

パブリックリポジトリからパッケージをインストールする

パブリック IP アドレスを持つ他のリポジトリでホストされているパッケージをインストールできます。

パッケージは、デフォルトの pip ツールでインストールされるように適切に構成されている必要があります。

パブリックアドレスを持つパッケージリポジトリからインストールするには:

pip.conf ファイルを作成し、必要に応じて次の情報をファイルに含めます。
- リポジトリの URL（index-url パラメータ内）
- リポジトリの認証情報にアクセスする
- デフォルト以外の pip インストールオプション
例:
```
[global]
index-url=https://example.com/
```
（省略可）複数のリポジトリからパッケージを取得する必要がある場合があります。たとえば、インストールする特定のパッケージが公開リポジトリに含まれているときに、PyPI から他のすべてのパッケージをインストールする場合など、です。
1. Artifact Registry 仮想リポジトリを構成します。
2. 複数のリポジトリ（必要に応じて PyPI を含む）の構成を追加し、pip がリポジトリを検索する順序を定義します。
3. index-url パラメータに仮想リポジトリの URL を指定します。
環境のバケットの URI を決定します。
環境のバケット内の /config/pip/ フォルダに pip.conf ファイルをアップロードします。
使用可能ないずれかの方法を使用してパッケージをインストールします。

Artifact Registry リポジトリからパッケージをインストールする

プロジェクトの Artifact Registry リポジトリにパッケージを保存し、そこからインストールするように環境を構成できます。

ロールと権限を構成する:

環境のサービスアカウントには、iam.serviceAccountUser ロールが必要です。
Cloud Build サービスアカウントに Artifact Registry リポジトリから読み取る権限があることを確認します。
VPC Service Controls を使用しているなど、プロジェクト内の他のサービスに対するアクセスが制限されている場合:
1. Artifact Registry リポジトリにアクセスするための権限を、Cloud Build サービスアカウントではなく、環境のサービスアカウントに割り当てます。
2. プロジェクトで Artifact Registry リポジトリへの接続が構成されていることを確認します。

Artifact Registry リポジトリからカスタム PyPI パッケージをインストールするには:

pip.conf ファイルを作成し、必要に応じて次の情報をファイルに含めます。
- Artifact Registry リポジトリの URL（index-url パラメータ内）
- リポジトリの認証情報にアクセスする
- デフォルト以外の pip インストールオプション
Artifact Registry リポジトリの場合は、リポジトリ URL に /simple/ を追加します。
```
[global]
index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
```
（省略可）複数のリポジトリからパッケージを取得する必要がある場合があります。たとえば、インストールする特定のパッケージが　Artifact Registry　リポジトリに含まれているときに、PyPI から他のすべてのパッケージをインストールする場合など、です。
1. Artifact Registry 仮想リポジトリを構成します。
2. 複数のリポジトリ（必要に応じて PyPI を含む）の構成を追加し、pip がリポジトリを検索する順序を定義します。
3. index-url パラメータに仮想リポジトリの URL を指定します。
環境のバケット内の /config/pip/ フォルダに pip.conf ファイルをアップロードします。例: gs://us-central1-example-bucket/config/pip/pip.conf。
使用可能ないずれかの方法を使用してパッケージをインストールします。

プライベートリポジトリからパッケージをインストールする

プロジェクトのネットワークでプライベートリポジトリをホストし、そこから Python パッケージをインストールする環境を構成できます。

ロールと権限を構成する:

Cloud Composer 環境のサービスアカウントには iam.serviceAccountUser ロールが必要です。
プロジェクトのネットワーク内のリポジトリからカスタム PyPI パッケージをインストールし、このリポジトリにパブリック IP アドレスがない場合:
1. このリポジトリにアクセスするための権限を環境のサービスアカウントに割り当てます。
2. このリポジトリへの接続性が、プロジェクトで構成されていることを確認します。

プロジェクトのネットワークでホストされているプライベートリポジトリからパッケージをインストールするには:

pip.conf ファイルを作成し、必要に応じて次の情報をファイルに含めます。
- プロジェクトのネットワーク内のリポジトリの IP アドレス
- リポジトリの認証情報にアクセスする
- デフォルト以外の pip インストールオプション
例:
```
[global]
index-url=https://192.0.2.10/
```
（省略可）複数のリポジトリからパッケージを取得する必要がある場合があります。たとえば、インストールする特定のパッケージがプライベートリポジトリに含まれているときに、PyPI から他のすべてのパッケージをインストールする場合など、です。
1. Artifact Registry 仮想リポジトリを構成します。
2. 複数のリポジトリ（必要に応じて PyPI を含む）の構成を追加し、pip がリポジトリを検索する順序を定義します。
3. index-url パラメータに仮想リポジトリの URL を指定します。
（省略可）2.2.1 以降のバージョンの Cloud Composer では、プライベートリポジトリからパッケージをインストールする際にカスタム証明書を使用できます。手順は次のとおりです。
1. 証明書ファイルを環境のバケット内の /config/pip/ フォルダにアップロードします。
  
  注意: 秘密鍵はアップロードしないでください。PEM 形式の一般公開証明書バンドルのみをアップロードします。証明書バンドルに正しいルート CA が含まれていることを確認します。
2. pip.conf で、証明書ファイルの名前を cert パラメータで指定します。/etc/pip/ フォルダは変更しないでください。
  
  例:
```
[global]
cert =/etc/pip/example-certificate.pem
```
環境のバケット内の /config/pip/ フォルダに pip.conf ファイルをアップロードします。例: gs://us-central1-example-bucket/config/pip/pip.conf。
使用可能ないずれかの方法を使用してパッケージをインストールします。

ローカルの Python ライブラリをインストールする

社内またはローカルの Python ライブラリをインストールするには、次の手順を行います。

環境のバケットにある dags/ フォルダ内のサブディレクトリに依存関係を配置します。サブディレクトリからモジュールをインポートするには、モジュールのパス内の各サブディレクトリに __init__.py パッケージのマーカーファイルが含まれている必要があります。

次の例では、依存関係は coin_module.py です。
```
dags/
  use_local_deps.py  # A DAG file.
  dependencies/
    __init__.py
    coin_module.py
```
DAG 定義ファイルから依存関係をインポートします。

例:

from dependencies import coin_module

共有オブジェクトライブラリに依存するパッケージを使用する

特定の PyPI パッケージは、システムレベルのライブラリに依存します。 Cloud Composer ではシステムライブラリはサポートされていませんが、次のオプションを使用できます。

KubernetesPodOperator を使用してください。Operator イメージをカスタムビルドイメージに設定します。システムの依存関係が満たされていないためインストール中にパッケージが失敗する場合は、このオプションを使用します。
環境のバケットに共有オブジェクトライブラリをアップロードします。PyPI パッケージが正常にインストールされたが実行時にエラーが発生した場合は、このオプションを使用します。
1. PyPI 依存関係の共有オブジェクトライブラリを手動で検索します（.so ファイル）。
2. 環境のバケットの /plugins フォルダに共有オブジェクトライブラリをアップロードします。
3. 次の環境変数を設定します。 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

プライベート IP 環境にパッケージをインストールする

このセクションでは、プライベート IP 環境にパッケージをインストールする方法について説明します。

プロジェクトの構成によっては、環境が公共のインターネットにアクセスできない場合があります。

パブリックインターネットアクセスのあるプライベート IP 環境

プライベート IP 環境で公共のインターネットにアクセスできる場合は、パブリック IP 環境用のオプションを使用してパッケージをインストールできます。

PyPI からインストールします。この場合、特別な構成は必要ありません。 PyPI からパッケージをインストールするで説明されている手順に従います。
パブリック IP アドレスを持つリポジトリからインストールする。プライベートリポジトリからパッケージをインストールするで説明されている手順に従います。
プロジェクトのネットワークでホストされているプライベート PyPI リポジトリからインストールします。

インターネットアクセスのないプライベート IP 環境

プライベート IP 環境が公共のインターネットにアクセスできない場合は、次のいずれかの方法でパッケージをインストールできます。

プロジェクトのネットワークでホストされているプライベート PyPI リポジトリを使用します。
プロジェクトのネットワーク内のプロキシサーバー VM を使用して、公共のインターネット上の PyPI リポジトリに接続します。環境のバケット内の /config/pip/pip.conf ファイルでプロキシアドレスを指定します。
パッケージの唯一のソースとして Artifact Registry リポジトリを使用します。これを行うには、説明に従って index-url パラメータを再定義します。
セキュリティポリシーで VPC ネットワークからの外部 IP アドレスへのアクセスが許可されている場合は、Cloud NAT を構成して、公共のインターネット上のリポジトリからのパッケージのインストールを有効にできます。
Python 依存関係を環境のバケット内の /dags フォルダに配置し、ローカルライブラリとしてインストールします。依存関係ツリーが大規模な場合は、この方法は適していません。

リソースロケーションの制限があるプライベート IP 環境にインストールする

リソースのロケーション制限の要件に合わせてプロジェクトを維持すると、一部のツールが使用できなくなります。特に、Cloud Build はパッケージのインストールには使用できないため、公共のインターネット上のリポジトリに直接アクセスできません。

このような環境に Python 依存関係をインストールするには、インターネット接続なしのプライベート IP 環境のガイダンスに従ってください。

VPC Service Controls の境界内のプライベート IP 環境への Python 依存関係のインストール

VPC Service Controls の境界でプロジェクトを保護すると、セキュリティがさらに制限されます。特に、Cloud Build はパッケージのインストールには使用できないため、公共のインターネット上のリポジトリに直接アクセスできません。

境界内にプライベート IP 環境用の Python 依存関係をインストールするには、インターネットアクセスのないプライベート IP 環境のガイダンスに従ってください。

Python 依存関係をインストールする

Cloud Composer イメージのプリインストール済み PyPI パッケージとカスタム PyPI パッケージについて

Cloud Composer 環境の PyPI パッケージを管理するオプション

始める前に

PyPI パッケージのリストを表示する

プリインストールされているパッケージを表示する

すべてのパッケージを表示

gcloud

カスタム PyPI パッケージを表示する

コンソール

gcloud

Cloud Composer 環境にカスタム パッケージをインストールする

PyPI からパッケージをインストールする

コンソール

gcloud

API

Terraform

パブリック リポジトリからパッケージをインストールする

Artifact Registry リポジトリからパッケージをインストールする

プライベート リポジトリからパッケージをインストールする

ローカルの Python ライブラリをインストールする

共有オブジェクト ライブラリに依存するパッケージを使用する

プライベート IP 環境にパッケージをインストールする

パブリック インターネット アクセスのあるプライベート IP 環境

インターネット アクセスのないプライベート IP 環境

リソース ロケーションの制限があるプライベート IP 環境にインストールする

VPC Service Controls の境界内のプライベート IP 環境への Python 依存関係のインストール

次のステップ

Cloud Composer 環境にカスタムパッケージをインストールする

パブリックリポジトリからパッケージをインストールする

プライベートリポジトリからパッケージをインストールする

共有オブジェクトライブラリに依存するパッケージを使用する

パブリックインターネットアクセスのあるプライベート IP 環境

インターネットアクセスのないプライベート IP 環境

リソースロケーションの制限があるプライベート IP 環境にインストールする