このチュートリアルでは、C++ ライブラリでカスタム コンテナを使用して、Dataflow HPC の高度な並列ワークフローを実行するパイプラインを作成します。このチュートリアルでは、Dataflow と Apache Beam を使用して、データを多くのコアで実行される関数に分散させるグリッド コンピューティング アプリケーションを実行する方法について説明します。
このチュートリアルでは、まず、Direct Runner を使用してパイプラインを実行する方法を説明します。次に、Dataflow Runner を使用してパイプラインを実行する方法を説明します。パイプラインをローカルで実行することで、デプロイする前にパイプラインをテストできます。
この例では、Cython のバインディングと、GMP ライブラリの関数を使用しています。使用するライブラリやバインディング ツールに関係なく、同じ原則をパイプラインに適用できます。
サンプルコードは GitHub で入手できます。
目標
C++ ライブラリでカスタム コンテナを使用するパイプラインを作成する。
Dockerfile を使用して Docker コンテナ イメージをビルドする。
コードと依存関係を Docker コンテナにパッケージ化する。
パイプラインをローカルで実行してテストする。
分散環境でパイプラインを実行する。
費用
このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。
- Artifact Registry
- Cloud Build
- Cloud Storage
- Compute Engine
- Dataflow
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。
このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。
始める前に
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Storage, Cloud Storage JSON, Compute Engine, Dataflow, Resource Manager, Artifact Registry, and Cloud Build APIs:
gcloud services enable compute.googleapis.com
dataflow.googleapis.com storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com -
Create local authentication credentials for your user account:
gcloud auth application-default login
-
Grant roles to your user account. Run the following command once for each of the following IAM roles:
roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="USER_IDENTIFIER" --role=ROLE
- Replace
PROJECT_ID
with your project ID. -
Replace
USER_IDENTIFIER
with the identifier for your user account. For example,user:myemail@example.com
. - Replace
ROLE
with each individual role.
- Replace
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Storage, Cloud Storage JSON, Compute Engine, Dataflow, Resource Manager, Artifact Registry, and Cloud Build APIs:
gcloud services enable compute.googleapis.com
dataflow.googleapis.com storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com -
Create local authentication credentials for your user account:
gcloud auth application-default login
-
Grant roles to your user account. Run the following command once for each of the following IAM roles:
roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="USER_IDENTIFIER" --role=ROLE
- Replace
PROJECT_ID
with your project ID. -
Replace
USER_IDENTIFIER
with the identifier for your user account. For example,user:myemail@example.com
. - Replace
ROLE
with each individual role.
- Replace
新しいパイプライン用にユーザー管理のワーカー サービス アカウントを作成し、このサービス アカウントに必要なロールを付与します。
サービス アカウントを作成するには、
gcloud iam service-accounts create
コマンドを実行します。gcloud iam service-accounts create parallelpipeline \ --description="Highly parallel pipeline worker service account" \ --display-name="Highly parallel data pipeline access"
サービス アカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。
roles/dataflow.admin
roles/dataflow.worker
roles/storage.objectAdmin
roles/artifactregistry.reader
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:parallelpipeline@PROJECT_ID.iam.gserviceaccount.com" --role=SERVICE_ACCOUNT_ROLE
SERVICE_ACCOUNT_ROLE
は、個々のロールに置き換えます。Google アカウントに、サービス アカウントのアクセス トークンを作成できるロールを付与します。
gcloud iam service-accounts add-iam-policy-binding parallelpipeline@PROJECT_ID.iam.gserviceaccount.com --member="user:EMAIL_ADDRESS" --role=roles/iam.serviceAccountTokenCreator
コードサンプルをダウンロードしてディレクトリを変更する
コードサンプルをダウンロードして、ディレクトリを変更します。GitHub リポジトリのコードサンプルには、このパイプラインの実行に必要なすべてのコードが含まれています。独自のパイプラインを構築する準備ができたら、このサンプルコードをテンプレートとして使用できます。
beam-cpp-example リポジトリのクローンを作成します。
git clone
コマンドを使用して GitHub リポジトリのクローンを作成します。git clone https://github.com/GoogleCloudPlatform/dataflow-sample-applications.git
アプリケーション ディレクトリに切り替えます。
cd dataflow-sample-applications/beam-cpp-example
パイプライン コード
このチュートリアルのパイプライン コードをカスタマイズできます。このパイプラインは次のタスクを完了します。
- 入力範囲内のすべての整数を動的に生成します。
- C++ 関数で整数を処理し、不正な値をフィルタリングします。
- 無効な値をサイドチャネルに書き込みます。
- 停止時間が発生するごとにカウントし、結果を正規化します。
- 出力を生成します。書式設定を行い、結果をテキスト ファイルに書き込みます。
- 単一の要素で
PCollection
を作成します。 map
関数で単一の要素を処理し、副入力として頻度PCollection
を渡します。PCollection
を処理し、単一の出力を生成します。
スターター ファイルは、次のようになります。
開発環境を設定する
Python の場合は Apache Beam SDK を使用します。
GMP ライブラリをインストールします。
apt-get install libgmp3-dev
依存関係をインストールするには、
requirements.txt
ファイルを使用します。pip install -r requirements.txt
Python バインディングをビルドするには、次のコマンドを実行します。
python setup.py build_ext --inplace
このチュートリアルの requirements.txt
ファイルをカスタマイズできます。スターター ファイルには、次の依存関係が含まれています。
パイプラインをローカルで実行する
パイプラインをローカルで実行すると、テストが容易になります。パイプラインをローカルで実行すると、パイプラインを分散環境にデプロイする前に、パイプラインが想定どおりに動作していることを確認できます。
パイプラインをローカルで実行するには、次のコマンドを使用します。このコマンドは、out.png
という名前のイメージを出力します。
python pipeline.py
Google Cloud リソースを作成する
このセクションでは、次のリソースを作成します。
- 一時的な保存場所と出力場所として使用する Cloud Storage バケット。
- パイプライン コードと依存関係をパッケージ化する Docker コンテナ。
Cloud Storage バケットを作成する
まず、Google Cloud CLI を使用して Cloud Storage バケットを作成します。このバケットは、Dataflow パイプラインによって一時ストレージの場所として使用されます。
バケットを作成するには、gcloud storage buckets create
コマンドを使用します。
gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION
次のように置き換えます。
- BUCKET_NAME: バケットの命名要件を満たす Cloud Storage バケットの名前。Cloud Storage のバケット名は、グローバルに一意である必要があります。
- LOCATION: バケットのロケーション。
コンテナ イメージを作成してビルドする
このチュートリアルの Dockerfile をカスタマイズできます。スターター ファイルは、次のようになります。
この Dockerfile には、FROM
、COPY
、RUN
の各コマンドが含まれています。これらのコマンドについては、Dockerfile リファレンスをご覧ください。
アーティファクトをアップロードするには、Artifact Registry リポジトリを作成します。各リポジトリには、サポートされている単一の形式のアーティファクトを含めることができます。
リポジトリのコンテンツはすべて、Google が所有し Google が管理する鍵か、顧客管理の暗号鍵を使用して暗号化されます。Artifact Registry では Google が所有し Google が管理する鍵がデフォルトで使用されるため、このオプションの構成は不要です。
ユーザーには少なくとも、リポジトリに対する Artifact Registry 書き込みアクセス権が必要です。
次のコマンドを実行して新しいリポジトリを作成します。このコマンドは
--async
フラグを使用します。実行中のオペレーションの完了を待たずにすぐに戻ります。gcloud artifacts repositories create REPOSITORY \ --repository-format=docker \ --location=LOCATION \ --async
REPOSITORY
は、リポジトリの名前に置き換えます。プロジェクト内のリポジトリのロケーションごとに、リポジトリ名は一意でなければなりません。Dockerfile を作成します。
パッケージを Apache Beam コンテナに含めるには、パッケージを
requirements.txt
ファイルの一部として指定する必要があります。requirements.txt
ファイルの一部としてapache-beam
を指定しないでください。Apache Beam コンテナには、すでにapache-beam
があります。イメージを push または pull する前に、Artifact Registry に対するリクエストを認証するように Docker を構成します。Docker リポジトリの認証を設定するには、次のコマンドを実行します。
gcloud auth configure-docker LOCATION-docker.pkg.dev
このコマンドにより、Docker 構成が更新されます。これで、Google Cloud プロジェクトの Artifact Registry に接続して、イメージを push できるようになりました。
Cloud Build で
Dockerfile
を使用して、Docker イメージをビルドします。作成した Dockerfile と一致するように、次のコマンドのパスを更新します。このコマンドは、ファイルをビルドして Artifact Registry リポジトリに push します。
gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/cpp_beam_container:latest .
コードと依存関係を Docker コンテナにパッケージ化する
このパイプラインを分散環境で実行するには、コードと依存関係を Docker コンテナにパッケージ化します。
docker build . -t cpp_beam_container
コードと依存関係をパッケージ化したら、パイプラインをローカルで実行してテストできます。
python pipeline.py \ --runner=PortableRunner \ --job_endpoint=embed \ --environment_type=DOCKER \ --environment_config="docker.io/library/cpp_beam_container"
このコマンドは、Docker イメージ内に出力を書き込みます。出力を表示するには、
--output
を使用してパイプラインを実行し、出力を Cloud Storage バケットに書き込みます。たとえば、次のコマンドを実行します。python pipeline.py \ --runner=PortableRunner \ --job_endpoint=embed \ --environment_type=DOCKER \ --environment_config="docker.io/library/cpp_beam_container" \ --output=gs://BUCKET_NAME/out.png
パイプラインを実行する
次に、Dataflow で Apache Beam パイプラインを実行します。それには、パイプライン コードを含むファイルを参照して、パイプラインに必要なパラメータを渡します。
シェルまたはターミナルで、Dataflow ランナーを使用してパイプラインを実行します。
python pipeline.py \
--runner=DataflowRunner \
--project=PROJECT_ID \
--region=REGION \
--temp_location=gs://BUCKET_NAME/tmp \
--sdk_container_image="LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/cpp_beam_container:latest" \
--experiment=use_runner_v2 \
--output=gs://BUCKET_NAME/out.png
コマンドでパイプラインを実行すると、Dataflow はジョブ ID とジョブ ステータス(Queued)を返します。ジョブのステータスが「Running」に変わり、ジョブグラフにアクセス可能になるまでに数分かかる場合があります。
結果を表示する
Cloud Storage バケットに書き込まれたデータを表示します。gcloud storage ls
コマンドを使用して、トップレベルのバケットの内容を一覧表示します。
gcloud storage ls gs://BUCKET_NAME
成功した場合、次のようなメッセージが返されます。
gs://BUCKET_NAME/out.png
クリーンアップ
このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。
プロジェクトを削除する
課金を停止する最も簡単な方法は、チュートリアル用に作成した Google Cloud プロジェクトを削除することです。
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
個々のリソースを削除する
プロジェクトを再利用する場合は、チュートリアル用に作成したリソースを削除します。
Google Cloud プロジェクトのリソースをクリーンアップする
Artifact Registry リポジトリを削除します。
gcloud artifacts repositories delete REPOSITORY \ --location=LOCATION --async
Cloud Storage バケットを削除します。このバケットだけでは料金は発生しません。
gcloud storage rm gs://BUCKET_NAME --recursive
認証情報を取り消す
ユーザー管理のワーカー サービス アカウントに付与したロールを取り消します。次の IAM ロールごとに次のコマンドを 1 回実行します。
roles/dataflow.admin
roles/dataflow.worker
roles/storage.objectAdmin
roles/artifactregistry.reader
gcloud projects remove-iam-policy-binding PROJECT_ID \ --member=serviceAccount:parallelpipeline@PROJECT_ID.iam.gserviceaccount.com \ --role=SERVICE_ACCOUNT_ROLE
-
Optional: Revoke the authentication credentials that you created, and delete the local credential file.
gcloud auth application-default revoke
-
Optional: Revoke credentials from the gcloud CLI.
gcloud auth revoke
次のステップ
- GitHub にあるサンプル アプリケーションを確認する。
- Dataflow でカスタム コンテナを使用する。
- Apache Beam でコンテナ環境を使用する方法を確認する。
- Google Cloud に関するリファレンス アーキテクチャ、図、ベスト プラクティスを確認する。Cloud アーキテクチャ センターをご覧ください。