Airflow Summit 2023
Airflow について理解を深め、専門知識を共有するための Airflow サミット 2023 カンファレンス(9 月 19~21 日)で、Airflow コミュニティにご参加ください。提案書募集開始

Cloud Composer 用の Python 依存関係をインストールする

Cloud Composer 1 | Cloud Composer 2

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

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

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

  • プリインストールされた PyPI パッケージは、環境の Cloud Composer イメージに含まれているパッケージです。各 Cloud Composer イメージには、Cloud Composer と Airflow のバージョンに固有の 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 の依存関係更新により、Docker イメージが Artifact Registry に生成されます。

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

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 パッケージを表示する

Console

  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 依存関係を追加、更新、削除するには、次の手順を行います。

Console

  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 ファイルには、要件指定子をそれぞれ 1 行に 1 つずつ記述する必要があります。

次に例を示します。

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" {
  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" {
  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
    • リポジトリの認証情報にアクセスする
    • デフォルト以外の pip インストール オプション

    例:

    [global]
    extra-index-url=https://example.com/
    
  2. pip.conf ファイルを環境のバケット内の /config/pip/ フォルダにアップロードします。次に例を示します。 gs://us-central1-example-bucket/config/pip/pip.conf

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

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

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

ロールと権限を構成します。

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

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

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

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

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

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

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

    • Artifact Registry リポジトリの URL
    • リポジトリの認証情報にアクセスする
    • デフォルト以外の pip インストール オプション
    • Artifact Registry リポジトリのみをパッケージのソースとして使用する場合は、index-url パラメータを再定義します。それ以外の場合は、デフォルトの PyPI パッケージ インデックス(pypi.python.org)に加えて、extra-index-url パラメータで指定したリポジトリが使用されます。

    Artifact Registry リポジトリの場合は、/simple/ をリポジトリ URL に追加します。

    [global]
    extra-index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
    
  2. pip.conf ファイルを環境のバケット内の /config/pip/ フォルダにアップロードします。例: gs://us-central1-example-bucket/config/pip/pip.conf

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

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

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

ロールと権限を構成します。

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

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

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

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

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

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

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

    例:

    [global]
    extra-index-url=https://192.0.2.10/
    
  2. pip.conf ファイルを環境のバケット内の /config/pip/ フォルダにアップロードします。例: gs://us-central1-example-bucket/config/pip/pip.conf

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

ローカルの 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 ファイルでプロキシ アドレスを指定します。
  • セキュリティ ポリシーで VPC ネットワークから外部 IP アドレスへのアクセスを許可している場合は、Cloud NAT を構成することで、公共のインターネット上のリポジトリからのパッケージのインストールを有効にできます。
  • Python 依存関係を環境のバケット内の /dags フォルダに配置し、ローカル ライブラリとしてインストールします。依存関係ツリーが大規模な場合は、この方法は適していません。

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

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

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

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

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

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

次のステップ