Cloud Composer の 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 パッケージを管理するオプション

始める前に

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

• PyPI 依存関係の更新により、Artifact Registry に Docker イメージが生成されます。

• 依存関係の競合が原因で更新が失敗した場合は、既存の依存関係内で環境が引き続き実行します。オペレーションが成功すると、DAG に新しくインストールされた Python 依存関係の使用を開始できます。

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

取得できる環境のパッケージ一覧にはいくつかの形式があります。

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

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

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

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

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

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

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

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

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

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

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

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

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

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

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

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

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

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

// 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"
      }
    }
  }
}

resource "google_composer_environment" "example" {
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

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

  config {

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

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

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

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

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

1. pip.conf ファイルを作成し、必要に応じて次の情報をファイルに含めます。

   • リポジトリの URL（index-url パラメータ内）
   • リポジトリの認証情報にアクセスする
   • デフォルト以外の pip インストール オプション

   例:

   [global]
   index-url=https://example.com/
   

2. （省略可）複数のリポジトリからパッケージを取得する必要がある場合があります。たとえば、インストールする特定のパッケージが公開リポジトリに含まれているときに、PyPI から他のすべてのパッケージをインストールする場合など、です。

   1. Artifact Registry 仮想リポジトリを構成します。
   2. 複数のリポジトリ（必要に応じて PyPI を含む）の構成を追加し、pip がリポジトリを検索する順序を定義します。
   3. index-url パラメータに仮想リポジトリの URL を指定します。

3. 環境のバケットの URI を決定します。

4. 環境のバケット内の /config/pip/ フォルダに pip.conf ファイルをアップロードします。

5. 使用可能ないずれかの方法を使用してパッケージをインストールします。

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

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

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

1. 環境のサービス アカウントには、iam.serviceAccountUser ロールが必要です。

2. Cloud Build サービス アカウントに Artifact Registry リポジトリから読み取る権限があることを確認します。

3. VPC Service Controls を使用しているなど、プロジェクト内の他のサービスに対するアクセスが制限されている場合:

   1. Artifact Registry リポジトリにアクセスするための権限を、Cloud Build サービス アカウントではなく、環境のサービス アカウントに割り当てます。

   2. プロジェクトで Artifact Registry リポジトリへの接続性が構成されていることを確認します。

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

1. 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/
   

2. （省略可）複数のリポジトリからパッケージを取得する必要がある場合があります。たとえば、インストールする特定のパッケージが　Artifact Registry　リポジトリに含まれているときに、PyPI から他のすべてのパッケージをインストールする場合など、です。

   1. Artifact Registry 仮想リポジトリを構成します。
   2. 複数のリポジトリ（必要に応じて PyPI を含む）の構成を追加し、pip がリポジトリを検索する順序を定義します。
   3. index-url パラメータに仮想リポジトリの URL を指定します。

3. 環境のバケット内の /config/pip/ フォルダに pip.conf ファイルをアップロードします。例: gs://us-central1-example-bucket/config/pip/pip.conf。

4. 使用可能ないずれかの方法を使用してパッケージをインストールします。

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

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

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

1. Cloud Composer 環境のサービス アカウントには iam.serviceAccountUser ロールが必要です。

2. プロジェクトのネットワーク内のリポジトリからカスタム PyPI パッケージをインストールし、このリポジトリにパブリック IP アドレスがない場合:

   1. このリポジトリにアクセスするための権限を環境のサービス アカウントに割り当てます。

   2. このリポジトリへの接続性が、プロジェクトで構成されていることを確認します。

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

1. pip.conf ファイルを作成し、必要に応じて次の情報をファイルに含めます。

   • プロジェクトのネットワーク内のリポジトリの IP アドレス
   • リポジトリの認証情報にアクセスする
   • デフォルト以外の pip インストール オプション

   例:

   [global]
   index-url=https://192.0.2.10/
   

2. （省略可）複数のリポジトリからパッケージを取得する必要がある場合があります。たとえば、インストールする特定のパッケージがプライベートリポジトリに含まれているときに、PyPI から他のすべてのパッケージをインストールする場合など、です。

   1. Artifact Registry 仮想リポジトリを構成します。
   2. 複数のリポジトリ（必要に応じて PyPI を含む）の構成を追加し、pip がリポジトリを検索する順序を定義します。
   3. index-url パラメータに仮想リポジトリの URL を指定します。

3. 環境のバケット内の /config/pip/ フォルダに pip.conf ファイルをアップロードします。例: gs://us-central1-example-bucket/config/pip/pip.conf。

4. 使用可能ないずれかの方法を使用してパッケージをインストールします。

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

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

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

   次の例では、依存関係は coin_module.py です。

   dags/
     use_local_deps.py  # A DAG file.
     dependencies/
       __init__.py
       coin_module.py
   

2. 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 環境のガイダンスに従ってください。

次のステップ

• パッケージのインストールに関するトラブルシューティング
• 更新とアップグレードのトラブルシューティング