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

Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3

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

Cloud Composer のパッケージについて

このセクションでは、Cloud Composer で PyPI パッケージがどのように機能するかについて説明します。

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 にあり、外部依存関係がありません。
KubernetesPodOperatorGKE オペレーター pip からインストールできない外部依存関係(dist-packages など)、または内部の pip サーバー上にある外部依存関係が必要な場合。このオプションでは、より多くの設定とメンテナンスが必要になります。他のオプションが機能しない場合にのみ、これを考慮してください。

始める前に

  • 環境の更新オペレーションをトリガーできるロールが必要です。また、環境のサービス アカウントには、更新オペレーションの実行に十分な権限を持つロールが必要です。

  • ご使用の環境が VPC Service Controls の境界で保護されている場合に PyPI の依存関係をインストールするには、サービス境界によって保護されているサービスへのアクセス権とともに追加のユーザー ID を付与し、プライベート PyPI リポジトリに対するサポートを有効にする必要があります。

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

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

  • 依存関係の競合が原因で更新が失敗した場合は、既存の依存関係内で環境が引き続き実行します。オペレーションが成功すると、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 パッケージを表示する

コンソール

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

    [環境] に移動

  2. 環境のリストで、ご利用の環境の名前をクリックします。[環境の詳細] ページが開きます。

  3. [PyPI パッケージ] タブに移動します。

gcloud

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

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

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

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

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

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

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

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

コンソール

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

    [環境] に移動

  2. 環境のリストで、ご利用の環境の名前をクリックします。[環境の詳細] ページが開きます。

  3. [PyPI パッケージ] タブに移動します。

  4. [編集] をクリックします。

  5. [パッケージを追加] をクリックします。

  6. [PyPI パッケージ] セクションで、オプションの追加情報とバージョン指定子とともにパッケージ名を指定します。

    次に例を示します。

    • scikit-learn
    • scipy>=0.13.3
    • nltk[machine_learning]
  7. [保存] をクリックします。

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 リクエストを作成します。

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

  1. updateMask パラメータで、マスクを指定します。

    • config.softwareConfig.pypiPackages マスクを使用して、既存のすべてのパッケージを指定したパッケージに置き換えます。指定しないパッケージは削除されます。
    • config.softwareConfig.envVariables.PACKAGE_NAME を使用して、特定のパッケージを追加または更新します。複数のパッケージを追加または更新するには、複数のマスクをカンマで区切って指定します。
  2. リクエストの本文で、パッケージと、バージョンと追加情報の値を指定します。

    {
      "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 ツールでインストールされるように適切に構成されている必要があります。

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

  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. (省略可)2.2.1 以降のバージョンの Cloud Composer では、プライベート リポジトリからパッケージをインストールする際にカスタム証明書を使用できます。手順は次のとおりです。

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

    2. pip.conf で、証明書ファイルの名前を cert パラメータで指定します。/etc/pip/ フォルダは変更しないでください。

      例:

      [global]
      cert =/etc/pip/example-certificate.pem
      
  4. 環境のバケット内の /config/pip/ フォルダに pip.conf ファイルをアップロードします。例: gs://us-central1-example-bucket/config/pip/pip.conf

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

ローカルの 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 環境用のオプションを使用してパッケージをインストールできます。

インターネット アクセスのないプライベート 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 環境のガイダンスに従ってください。

次のステップ