Dataflow のカスタム コンテナ イメージをビルドする

このドキュメントでは、Dataflow ジョブのカスタム コンテナ イメージを作成する方法について説明します。

要件

Dataflow のカスタム コンテナ イメージは、次の要件を満たす必要があります。

  • Apache Beam SDK と必須の依存関係がインストールされている必要があります。デフォルトの Apache Beam SDK イメージから始めることをおすすめします。詳細については、このドキュメントのベースイメージを選択するをご覧ください。
  • /opt/apache/beam/boot スクリプトは、コンテナ起動時の最後のステップとして実行する必要があります。このスクリプトは、ワーカー環境を初期化し、SDK ワーカー プロセスを開始します。このスクリプトは、Apache Beam SDK イメージのデフォルトの ENTRYPOINT です。ただし、別のベースイメージを使用する場合や、デフォルトの ENTRYPOINT をオーバーライドする場合は、スクリプトを明示的に実行する必要があります。詳細については、このドキュメントのコンテナのエントリポイントを変更するをご覧ください。
  • コンテナ イメージが、Dataflow ジョブのワーカー VM のアーキテクチャをサポートしている必要があります。ARM VM でカスタム コンテナを使用する場合は、マルチアーキテクチャ イメージをビルドすることをおすすめします。詳細については、マルチアーキテクチャ コンテナ イメージをビルドするをご覧ください。

始める前に

  1. インストールされている Apache Beam SDK のバージョンが、Runner v2 とお使いの言語バージョンに対応していることを確認します。詳細については、Apache Beam SDK をインストールするをご覧ください。

  2. コンテナ イメージをローカルでテストするには、Docker がインストールされている必要があります。詳細については、Docker を取得するをご覧ください。

  3. Artifact Registry リポジトリを作成します。Docker イメージの形式を指定します。ユーザーには、少なくともリポジトリに対する Artifact Registry 書き込みアクセス権が必要です。

    新しいリポジトリを作成するには、gcloud artifacts repositories create コマンドを実行します。

    gcloud artifacts repositories create REPOSITORY \
  --repository-format=docker \
  --location=REGION \
  --async

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

    • REPOSITORY: リポジトリの名前。リポジトリ名は、プロジェクト内のロケーションごとに一意である必要があります。
    • REGION: Dataflow ジョブをデプロイするリージョン。コマンドを実行する場所に近接した Dataflow リージョンを選択します。値には有効なリージョン名を指定してください。リージョンとロケーションの詳細については、Dataflow のロケーションをご覧ください。

    この例では、--async フラグを使用しています。オペレーションの完了を待たずに、コマンドがすぐに返されます。

  4. Artifact Registry のリクエストを認証するように Docker を構成するには、gcloud auth configure-docker コマンドを実行します。

    gcloud auth configure-docker REGION-docker.pkg.dev

    このコマンドにより、Docker 構成が更新されます。これで、Google Cloud プロジェクトの Artifact Registry に接続して、イメージを push できるようになりました。

ベースイメージを選択する

ベース コンテナ イメージとして Apache Beam SDK イメージから始めることをおすすめします。デフォルトのイメージは、Apache Beam リリースの一環として Docker Hub にリリースされます。

Apache Beam のベースイメージを使用する

Apache Beam SDK イメージをベースイメージとして使用するには、FROM 命令でコンテナ イメージを指定し、独自のカスタマイズを追加します。

Java

この例では、Java 8 を Apache Beam SDK バージョン 2.58.0 で使用しています。

FROM apache/beam_java8_sdk:2.58.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

カスタム コンテナのランタイム バージョンは、パイプラインの開始に使用するランタイムと一致する必要があります。たとえば、パイプラインをローカルの Java 11 環境から開始する場合は、FROM 行に apache/beam_java11_sdk:... を記述し、Java 11 環境を指定する必要があります。

Python

この例では、Python 3.10 を Apache Beam SDK バージョン 2.58.0 で使用しています。

FROM apache/beam_python3.10_sdk:2.58.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

カスタム コンテナのランタイム バージョンは、パイプラインの開始に使用するランタイムと一致する必要があります。たとえば、パイプラインをローカルの Python 3.10 環境から開始する場合は、FROM 行に apache/beam_python3.10_sdk:... を記述し、Python 3.10 環境を指定する必要があります。

Go

この例では、Go を Apache Beam SDK バージョン 2.58.0 で使用しています。

FROM apache/beam_go_sdk:2.58.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

カスタム ベースイメージを使用する

別のベースイメージを使用する場合や、デフォルトの Apache Beam イメージの一部（OS バージョンやパッチなど）を変更する必要がある場合は、マルチステージ ビルド プロセスを使用します。デフォルトの Apache Beam ベースイメージから必要なアーティファクトをコピーします。

/opt/apache/beam/boot スクリプトを実行するように ENTRYPOINT を設定します。これにより、ワーカー環境が初期化され、SDK ワーカー プロセスが開始されます。このエントリポイントを設定しないと、Dataflow ワーカーが正しく起動しません。

次の例は、Apache Beam SDK からファイルをコピーする Dockerfile を示しています。

Java

FROM openjdk:8

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_java8_sdk:2.58.0 /opt/apache/beam /opt/apache/beam

# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]

Python

FROM python:3.10-slim

# Install SDK.
RUN pip install --no-cache-dir apache-beam[gcp]==2.58.0

# Verify that the image does not have conflicting dependencies.
RUN pip check

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_python3.10_sdk:2.58.0 /opt/apache/beam /opt/apache/beam

# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]

この例では、必要な依存関係（この場合は Python 3.10 と pip）が既存のベースイメージにインストールされていることを前提としています。イメージに Apache Beam SDK をインストールすると、必要な SDK 依存関係がイメージに含まれるため、ワーカーの起動時間が短縮されます。

重要: RUN、COPY 手順で指定された SDK バージョンは、パイプラインの起動に使用されたバージョンと一致する必要があります。

Go

FROM golang:latest

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_go_sdk:2.58.0 /opt/apache/beam /opt/apache/beam

# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]

コンテナのエントリポイントを変更する

コンテナ起動時にカスタム スクリプトを実行する場合、スクリプトは /opt/apache/beam/boot を実行して終了する必要があります。コンテナ起動時に Dataflow から渡された引数は、デフォルトの起動スクリプトに渡す必要があります。次の例は、デフォルトの起動スクリプトを呼び出すカスタム起動スクリプトを示しています。

#!/bin/bash

echo "This is my custom script"
# ...

# Pass command arguments to the default boot script.
/opt/apache/beam/boot "$@"

Dockerfile で、スクリプトを呼び出すように ENTRYPOINT を設定します。

Java

FROM apache/beam_java8_sdk:2.58.0

COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]

Python

FROM apache/beam_python3.10_sdk:2.58.0

COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]

Go

FROM apache/beam_go_sdk:2.58.0

COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]

イメージをビルドして push する

Cloud Build または Docker を使用してコンテナ イメージをビルドし、Artifact Registry リポジトリに push できます。

Cloud Build

ファイルをビルドして Artifact Registry リポジトリに push するには、gcloud builds submit コマンドを実行します。

  gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/FILE_NAME:TAG .

Docker

docker build . --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/FILE_NAME:TAG
docker push REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/FILE_NAME:TAG

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

  • REGION: Dataflow ジョブをデプロイするリージョン。REGION 変数の値は有効なリージョン名にする必要があります。
  • PROJECT_ID: プロジェクト名またはユーザー名。
  • REPOSITORY: イメージ リポジトリの名前。
  • FILE_NAME: Dockerfile の名前。
  • TAG: イメージタグ。バージョニングされたコンテナの SHA またはタグを必ず指定してください。:latest タグや可変タグは使用しないでください。

Python の依存関係を事前にインストールする

このセクションは、Python パイプラインに適用されます。

Python Dataflow ジョブを起動する場合、ランタイムに --requirements_file または --extra_packages オプションを使用して追加の依存関係を指定できます。詳細については、Python パイプラインの依存関係の管理をご覧ください。追加の依存関係が各 Dataflow ワーカー コンテナにインストールされます。ジョブを初めて開始したときや、自動スケーリング中に依存関係がインストールされると、多くの場合、新しく起動したすべての Dataflow ワーカーで CPU 使用率が高くなり、ウォームアップ時間が長くなります。

依存関係が繰り返しインストールされないようにするには、すべての依存関係がプリインストールされたカスタム Python SDK コンテナ イメージを事前にビルドします。このステップは、Dockerfile を使用してビルド時に行うことも、ジョブの送信時に行うこともできます。

ワーカーはコンテナの起動時に新しい仮想 Python 環境を作成します。このため、仮想環境を作成するのではなく、デフォルト（グローバル）の Python 環境に依存関係をインストールします。コンテナ イメージで仮想環境を有効にしても、この環境がジョブの開始時に有効になっていない可能性があります。詳細については、一般的な問題をご覧ください。

Dockerfile を使用して事前にインストールする

Python カスタム コンテナに依存関係を直接追加するには、次のコマンドを使用します。

FROM apache/beam_python3.10_sdk:2.58.0

COPY requirements.txt .

# Pre-install Python dependencies. For reproducibile builds,
# supply all of the dependencies and their versions in a requirements.txt file.
RUN pip install -r requirements.txt

# You can also install individual dependencies.
RUN pip install lxml
# Pre-install other dependencies.
RUN apt-get update \
  && apt-get dist-upgrade \
  && apt-get install -y --no-install-recommends ffmpeg

--sdk_container_image と --sdk_location のパイプライン オプションを使用してジョブを送信します。--sdk_location オプションを使用すると、ジョブの起動時に SDK がダウンロードされなくなります。SDK がコンテナ イメージから直接取得されます。

次の例では、wordcount サンプル パイプラインを実行します。

python -m apache_beam.examples.wordcount \
  --input=INPUT_FILE \
  --output=OUTPUT_FILE \
  --project=PROJECT_ID \
  --region=REGION \
  --temp_location=TEMP_LOCATION \
  --runner=DataflowRunner \
  --experiments=use_runner_v2 \
  --sdk_container_image=IMAGE_URI
  --sdk_location=container

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

  • INPUT_FILE: パイプラインの入力ファイル
  • OUTPUT_FILE: 出力を書き込むパス。
  • PROJECT_ID: Google Cloud プロジェクト ID
  • REGION: Dataflow ジョブをデプロイするリージョン
  • TEMP_LOCATION: 一時ジョブファイルをステージングするための Dataflow 用の Cloud Storage パス
  • IMAGE_URI: カスタム コンテナ イメージの URI

ジョブの送信時にコンテナ イメージを事前にビルドする

コンテナ イメージを事前にビルドすると、ジョブの起動前にパイプラインの依存関係をプリインストールできます。カスタム コンテナ イメージをビルドする必要はありません。

ジョブの送信時に追加の Python 依存関係を含むコンテナを事前にビルドするには、次のパイプライン オプションを使用します。

  • --prebuild_sdk_container_engine=[cloud_build | local_docker]。このフラグを設定すると、Apache Beam はカスタム コンテナを生成し、--requirements_file オプションと --extra_packages オプションで指定されたすべての依存関係をインストールします。このフラグは、次の値をサポートしています。

    • cloud_build。Cloud Build を使用してコンテナをビルドします。プロジェクトで Cloud Build API を有効にする必要があります。
    • local_docker。ローカルの Docker インストールを使用してコンテナをビルドします。

  • --docker_registry_push_url=IMAGE_PATH。IMAGE_PATH は、Artifact Registry フォルダに置き換えます。

  • --sdk_location=container。このオプションを使用すると、ジョブの起動時にワーカーが SDK をダウンロードできなくなります。SDK はコンテナ イメージから直接取得されます。

次の例では、Cloud Build を使用してイメージを事前にビルドします。

python -m apache_beam.examples.wordcount \
  --input=INPUT_FILE \
  --output=OUTPUT_FILE \
  --project=PROJECT_ID \
  --region=REGION \
  --temp_location=TEMP_LOCATION \
  --runner=DataflowRunner \
  --disk_size_gb=DISK_SIZE_GB \
  --experiments=use_runner_v2 \
  --requirements_file=./requirements.txt \
  --prebuild_sdk_container_engine=cloud_build \
  --docker_registry_push_url=IMAGE_PATH \
  --sdk_location=container

事前ビルド機能には、Apache Beam SDK for Python バージョン 2.25.0 以降が必要です。

SDK コンテナ イメージの事前ビルド ワークフローでは、--sdk_container_image パイプライン オプションで渡されたイメージをベースイメージとして使用します。このオプションが設定されていない場合、デフォルトでは Apache Beam イメージがベースイメージとして使用されます。

同じ依存関係と SDK バージョンを使用する別のジョブで、ビルド済みの Python SDK コンテナ イメージを再利用できます。イメージを再利用するには、--sdk_container_image パイプライン オプションを使用してビルド済みコンテナ イメージの URL を他のジョブに渡します。依存関係オプション --requirements_file、--extra_packages、--setup_file を削除します。

イメージを再利用する予定がない場合は、ジョブの完了後にイメージを削除します。イメージを削除するには、gcloud CLI を使用するか、Google Cloud コンソールの Artifact Registry ページを使用します。

イメージが Artifact Registry に保存されている場合は、artifacts docker images delete コマンドを使用します。

   gcloud artifacts docker images delete IMAGE --delete-tags

一般的な問題

  • ジョブにプライベート PyPi ミラーからの追加の Python 依存関係があり、リモートの Cloud Build ジョブで pull できない場合は、ローカル Docker オプションを使用するか、Dockerfile を使用してコンテナをビルドしてみてください。

  • Cloud Build ジョブが docker exit code 137 で失敗する場合、ビルドジョブがメモリ不足を示している可能性があります。これは、インストールされる依存関係のサイズが原因です。--cloud_build_machine_type=machine_type を渡して、より大きな Cloud Build ワーカー マシンタイプを使用します。ここで、machine_type は次のいずれかのオプションです。

    • n1-highcpu-8
    • n1-highcpu-32
    • e2-highcpu-8
    • e2-highcpu-32

    デフォルトでは、Cloud Build はマシンタイプ e2-medium を使用します。

  • Apache Beam 2.44.0 以降では、カスタム コンテナの起動時にワーカーが仮想環境を作成します。コンテナが独自の仮想環境を作成して依存関係をインストールする場合、それらの依存関係は破棄されます。この動作により、次のようなエラーが発生する可能性があります。

    ModuleNotFoundError: No module named '<dependency name>'

    この問題を回避するには、デフォルト（グローバル）の Python 環境に依存関係をインストールします。回避策として、コンテナ イメージで次の環境変数を設定して、Beam 2.48.0 以降でこの動作を無効にします。

    ENV RUN_PYTHON_SDK_IN_DEFAULT_ENVIRONMENT=1

次のステップ