Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

オーケストレーションパイプラインをデプロイする

このページでは、オーケストレーションパイプラインのデプロイ環境構成を作成するプロセスについて説明します。

デプロイ環境について

プロジェクトには 1 つ以上のデプロイ環境を設定できます。各デプロイ環境の構成では、この環境に属するパイプラインとリソースのデプロイ方法を定義します。たとえば、開発用のデプロイ環境と本番環境用のデプロイ環境を設定できます。これらのデプロイ環境には、別々のパイプラインセットを設定し、異なるランナー環境で実行できます。

各デプロイ環境にはランナー環境が必要です。 Managed Airflow は、パイプラインがデプロイされた後に実行するオーケストレーションエンジンです。プレビューでは、サポートされているランナー環境は、デプロイ環境に割り当てた Managed Airflow 環境のみです。

デプロイ環境にアーティファクトバケットを指定できます。このバケットには、パイプラインが実行するバージョン管理されたパイプラインアセットと、アーティファクトバケットに出力される一部のアクションの結果が保存されます。

パイプラインバンドルについて

オーケストレーションパイプラインは、パイプラインバンドルにデプロイされます。パイプラインバンドルには、共通のデプロイサイクルを共有する 1 つ以上のパイプラインとパイプラインアセットが含まれています。

各バンドルには複数のバージョンを設定できます。

バンドルをデプロイすると、特定のバージョンのバンドルパッケージ内のすべてのパイプラインと付随するスクリプトが一緒にデプロイされます。
バンドルの現在のバージョンは 1 つだけです（最新バージョンとしてデプロイされたもの）。以前のコードバージョンでトリガーされた個々のパイプライン実行は、中断されることなく続行されます。
現在のバージョンとは異なるバージョンでパイプラインを手動でトリガーすることはできません。
パイプラインがバンドルから削除され、バンドルの新しいバージョンがデプロイされた場合、パイプラインは新しいバージョンでは実行されませんが、以前にアクティブに実行されていた実行は続行されます。

始める前に

ランナー環境がすでに作成されていることを確認します。

パイプラインバンドルのスキャフォールディングを初期化する

Orchestration Pipelines には、リポジトリ内のオーケストレーションパイプラインのスキャフォールディングを初期化する gcloud CLI コマンドが用意されています。

スキャフォールディングには次のものが含まれます。

orchestration-pipeline.yaml: スケジュールは含まれていますが、アクションが定義されていないパイプライン定義の例。
deployment.yaml: パイプラインのデプロイ方法を定義するパイプラインデプロイ構成の例。ランナー環境、アーティファクトバケット、パイプラインアクションで使用されるその他のリソースの構成が含まれています。
.github/workflows/validate.yaml：main ブランチへの pull リクエストが作成されたときにパイプラインを検証する GitHub アクションの例。
.github/workflows/deploy.yaml: GitHub リポジトリの main ブランチに変更をマージしたときにパイプラインをデプロイする GitHub アクションの例。

オーケストレーションパイプラインを初期化するには:

リポジトリまたはプロジェクトディレクトリに移動します。コマンドを実行すると、実行したディレクトリに新しいファイルが作成されます。
次の gcloud CLI コマンドを実行します。
```
gcloud beta orchestration-pipelines init PIPELINE_NAME \
  --environment DEPLOYMENT_ENVIRONMENT \
  --composer-environment RUNNER_ENVIRONMENT \
  --artifacts-bucket ARTIFACTS_BUCKET_NAME \
  --project PROJECT_ID \
  --region REGION \
  --service-account SERVICE_ACCOUNT
```
次のように置き換えます。
- PIPELINE_NAME: 初期パイプラインの名前。
- DEPLOYMENT_ENVIRONMENT: 初期デプロイ環境の名前。
- RUNNER_ENVIRONMENT: ランナー環境の名前。
- ARTIFACTS_BUCKET_NAME: パイプラインアクションアーティファクトの保存に使用される Cloud Storage バケット。gs:// 接頭辞は付けません。
- PROJECT_ID: ランナー環境が配置されているプロジェクトのプロジェクト ID。 Google Cloud
- REGION: ランナー環境が配置されているリージョン。
- SERVICE_ACCOUNT: 変数としてプリセットされるサービスアカウント。この値は、ランナー環境のサービスアカウントに設定します。この変数は、パイプライン定義とリソースプロファイルで使用できます。たとえば、偽装チェーンを使用するアクションの impersonationChainパラメータの値として使用できます。
  
  ランナー環境のサービスアカウントは、環境の詳細を表示して取得できます。gcloud CLI では、環境サービスアカウントは nodeConfig.serviceAccount キーに指定されます。
  
  重要: このパラメータは変数の値を指定します。ランナー環境は、作成時に指定した元のサービスアカウントで実行されます 。変数の値を別のサービスアカウントに変更しても、ランナー環境のサービスアカウントを使用してすべてのパイプラインアクションが実行されます。
例:
```
gcloud beta orchestration-pipelines init example-pipeline \
  --environment development \
  --composer-environment production-runner-us-central1 \
  --artifacts-bucket production-artifacts \
  --project example-production-project \
  --region us-central1 \
  --service-account example-account@example-project.iam.gserviceaccount.com
```

ランナー環境の構成を追加する

ランナー環境は、デプロイ環境の composer_environment キーで指定します。複数のデプロイ環境を使用する場合は、それぞれに個別のランナー環境を指定できます。

開発環境の構成の project キーと region キーとともに、composer_environment キーのランナー環境の名前を指定すると、パイプラインがデプロイされるランナー環境を指定できます。

次の例では、example-development-project プロジェクトの us-central1 リージョンにある example-runner-environment という名前のランナー環境を追加しています。

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "example-runner-environment"
    ...

ランナー環境の構成を調整する

ランナー環境は、他の Managed Service for Apache Airflow 環境と同様に構成できます。

Python の依存関係をインストールして、たとえばパイプラインの Python スクリプトをランナー環境でローカルに実行します。
環境をスケーリングしてリソースを増減したり、ランナー環境で Airflow ワーカーをスケーリングする方法を変更したりします。
Airflow 構成オプションをオーバーライドして Airflow を構成します。

パイプラインアセットを追加してアクションを構成する

パイプラインの定義ファイルを編集して、アクションとパイプラインアセットを含めます。

コード例とアクションパラメータの説明については、Orchestration Pipelines DSL リファレンスをご覧ください。
詳細なチュートリアルについては、 Google Cloud Data Agent Kit 拡張機能のドキュメントでデータエンジニアリングパイプラインを構築するをご覧ください。

Hello World アクションの例

最小限のパイプラインアクションの例を次に示します。これを使用して、デプロイ環境の構成をテストできます。

次のアクションをスキャフォールディングパイプラインに追加し、actions: [] を置き換えます。

actions:
  - python:
      name: "hello_world_script_run"
      executionTimeout: "30m"
      mainFilePath: "scripts/hello_world.py"
      pythonCallable: "main"
      engine:
        local: {}

リポジトリに scripts という名前の新しいサブディレクトリを作成し、次のファイルを /scripts/hello_world.py として保存します。
```
def main():
  print("Hello, World!")
```

パイプラインを検証する

検証コマンドは、パイプライン定義ファイルの構文と型の正確性をチェックします。また、 Google Cloud プロジェクトや Managed Service for Apache Airflow 環境などのリソースのセマンティックチェックも、デプロイ構成ファイルとパイプライン定義ファイルの両方で実行します。

デフォルトでは、リモートランナー環境への接続など、すべてのデプロイ環境の完全な検証が実行されます。次のパラメータを使用して、デプロイ構成の特定の部分を検証できます。

--mode: syntax-only に設定すると、リモートランナー環境に接続しません。デフォルトは full です。
--environment: 特定の環境のみを検証します。
--pipeline-paths: 検証するパイプライン定義ファイルのカンマ区切りのリスト。
--substitutions と --substitutions-file: 検証中にデプロイ構成パラメータを置き換えます。

このコマンドは、ローカルパイプラインバージョンをデプロイする前のクイックチェックとして、また CI/CD ワークフローの一部として GitHub アクションとして実行できます。

リポジトリで次のコマンドを実行して、パイプラインを検証します。

gcloud beta orchestration-pipelines validate

パイプラインバンドルをデプロイする

このセクションでは、パイプラインをデプロイするさまざまな方法について説明します。

Orchestration Pipelines では、パイプラインバンドルをデプロイする方法が 2 つあります。これらのアプローチは、開発とリリースワークフローのさまざまな段階で連携するように設計されています。

ローカルバンドルバージョンをデプロイする: パイプラインアセット、パイプライン定義、デプロイ構成の現在のバージョンをデプロイします。新しいバンドル ID は、ワークスペース名とバンドル内のファイルの md5 に基づいて自動生成されます。

このデプロイタイプは開発を目的としています。また、パイプラインをステージングランナー環境にデプロイする別のデプロイ構成を作成することをおすすめします。
commit された変更をデプロイする: パイプラインアセット、パイプライン定義、デプロイ構成に変更を commit したら、パイプラインバンドルの新しいバージョンをランナー環境にデプロイできます。新しいバンドルの ID は、リポジトリ内の Git commit SHA にリンクされます。

このデプロイタイプは、CI/CD の一部として実行することを目的としています（GitHub アクションなど）。commit された変更をローカル Git リポジトリからデプロイすることもできます。

Orchestration Pipelines では、パイプライン定義ファイルとデプロイ構成ファイルでパラメータを置き換える方法がいくつかあります。これは、ローカル開発と GitHub アクションで実行されるコマンドの両方でパイプラインをデプロイする場合に便利です。たとえば、gcloud CLI コマンドで --substitutions 引数を使用するか、環境変数を設定するか、 GitHub シークレットから値を取得して、パラメータを置き換えることができます。

デプロイコマンドを実行する

ローカル

ローカルバンドルバージョンをデプロイするには、--local 引数を使用します。

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT \
  --local

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

DEPLOYMENT_ENVIRONMENT: パイプラインのデプロイ環境。

例:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local

出力例には、パイプラインバンドルの名前とバージョン、デプロイステータスが含まれます。

Bundle ID: bundle-local-example-orchestrationpipelines
Version ID: local-14776d43ebba

...

--- Pipeline Deployment Status ---
Pipeline 'example-pipeline': [OK] (Status: HEALTHY)

--- Pipeline Deployment full details ---

...

commit 済み

変更をデプロイするには、リポジトリに変更が commit されていることを確認します。gcloud CLI で次のコマンドを実行します。

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

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

DEPLOYMENT_ENVIRONMENT: パイプラインのデプロイ環境。

例:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment

出力例には、パイプラインバンドルの名前とバージョン、デプロイステータスが含まれます。

Bundle ID: bundle-local-example-orchestrationpipelines
Version ID: local-14776d43ebba

...

--- Pipeline Deployment Status ---
Pipeline 'example-pipeline': [OK] (Status: HEALTHY)

--- Pipeline Deployment full details ---

...

GitHub アクション

パイプラインスキャフォールディングには、GitHub アクションの例が 2 つあります。これを使用すると、 GitHub アクションを使用してパイプラインのデプロイと検証を開始できます。これらのファイルを GitHub にアップロードすると、リポジトリはこれらのアクションで構成されます。より複雑な GitHub アクションの構成については、 GitHub Actions を使用したデプロイを GitHub ドキュメントでご覧ください。

GitHub アクションの例を使用するには:

GitHub アクションから gcloud CLI コマンドを実行する別のサービスアカウントを作成します。
デプロイコマンドと検証コマンドの実行を許可するロールをこのサービスアカウントに割り当てます。

重要: この目的で Google アカウントを使用することはできません。ランナー環境のサービスアカウントは、このタスクに対して権限が広すぎるため使用しないでください。
このサービスアカウントキーをこのサービスアカウントに作成します。
GCP_SA_KEY シークレットを GitHub リポジトリに追加し、その値を作成したサービスアカウントキーに設定します。シークレットの追加の詳細については、 GitHub Actions でシークレットを使用するをご覧ください。

デプロイ構成

このセクションでは、デプロイ環境に適用できる追加の構成について説明します。

別のパイプラインを追加または削除する

既存のデプロイ環境に別のパイプラインを追加するには:

パイプライン定義ファイルとパイプラインアセットをリポジトリに追加します。
デプロイ構成で、新しいパイプライン定義ファイルを指す値を持つ新しい source キーを追加します。

例:

environments:
  dev:

    ...

    pipelines:
      - source: example-pipeline.yaml
      - source: another-pipeline.yaml

パイプラインを削除するには:

デプロイ構成で、パイプラインの source キーを削除します。
パイプライン定義ファイルとパイプラインアセットをリポジトリから削除します。
パイプラインの新しいバージョンをデプロイします。パイプラインは新しいバンドルバージョンには存在しません。

別のデプロイ環境を追加する

別のデプロイ環境を追加するには:

デプロイ構成で、environments マッピングに新しいキーを追加します。
デプロイ構成とパイプライン定義で変数とデプロイ構成変数を使用して、各環境に属する Google Cloud リソースを区別する必要があるパイプラインアクションを実行します。

例:

environments:

  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "development-runner-us-central1"
    ...
    variables:
      service_account: "another-service-account@example-development-project.iam.gserviceaccount.com"
    ...

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    ...
    variables:
      service_account: "example-account@example-project.iam.gserviceaccount.com"

変数、シークレット、置換

デプロイ構成で変数を定義したら、パイプライン定義とリソースプロファイルで使用できます。

カスタム変数を追加する

デプロイ構成の variables キーに独自の変数を追加できます。

デプロイ構成環境で、variables キーを追加します。
変数名と値のマッピングを追加します。
パイプライン定義とリソースプロファイルで変数の値を取得するには、変数の名前を二重中かっこで囲みます: {{ example_variable }}.

次の例では、2 つのデプロイ環境に同じ変数を設定しています。

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "development-runner-us-central1"
    artifact_storage:
      bucket: "development-artifacts"
      path_prefix: pipelines
    pipelines:
      - source: example-pipeline.yaml
    variables:
      service_account: "another-service-account@example-development-project.iam.gserviceaccount.com"
      network_uri: projects/example-development-project/global/networks/default

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    artifact_storage:
      bucket: "production-artifacts"
      path_prefix: pipelines
    pipelines:
      - source: example-pipeline.yaml
    variables:
      service_account: "example-account@example-project.iam.gserviceaccount.com"
      network_uri: projects/example-production-project/global/networks/vpc-main

次は、これらの変数を読み取る Managed Service for Apache Spark リソースプロファイルです。パイプライン定義ファイル（example-pipeline.yaml）のアクションは同じリソースプロファイルを使用できるため、本番環境と開発環境の間で調整する必要はありません。

profileId: serverless-standard
type: dataproc.session
definition:
  environmentConfig:
    execution_config:
      service_account: "{{ service_account }}"
      network_uri: "{{ network_uri }}"

デプロイ構成パラメータにアクセスする

デプロイ構成の一部のパラメータは変数としても使用できます。

project
region
composer_environment
COMMIT_SHA: Git リポジトリの現在の commit SHA。この変数は、ローカルパイプラインバンドルバージョンをデプロイするときに値を置き換えることで使用できます。これにより、commit SHA 値に依存するアクションは、正しいファイルコンテンツで引き続き動作します。

次の例では、パイプライン定義で、デプロイ構成パラメータ project と region に基づいてパイプラインアクションのデフォルトを設定しています。

pipelineId: example-pipeline
description: Example pipeline
runner: 'airflow'
owner: 'data-eng-team'
modelVersion: '1.0'
defaults:
  projectId: {{ project }}
  location: {{ region }}
  executionConfig:
    retries: 1

GitHub アクションシークレットにアクセスする

パイプライン定義ファイルとデプロイ構成ファイルで GitHub シークレットを使用できます。パイプラインが GitHub アクションを介してデプロイされると、これらのシークレットの値はパイプライン定義とデプロイ構成の両方に渡されます。

デプロイ中にアクセスできるシークレットを作成するには:

GitHub で、DEPLOY_VAR_ 接頭辞が付いたシークレットを追加します。例: DEPLOY_VAR_API_KEY。

シークレットの作成の詳細については、 GitHub Actions でシークレットを使用するを GitHub ドキュメントでご覧ください。
同じ環境変数を GitHub ワークフローに追加します。GitHub シークレットからこの変数の値を読み取ります。

例:
```
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_VAR_API_KEY: ${{ secrets.API_KEY }}

    steps:

    ...
```
ワークフローへの環境変数の追加の詳細については、 GitHub ドキュメントの変数に情報を保存するをご覧ください。
パイプライン定義ファイルとデプロイ構成で、変数名（DEPLOY_VAR_ 接頭辞なし）を使用します。例: {{ API_KEY }}。
（省略可）GitHub シークレットを使用するパイプラインのローカルバージョンをデプロイするには、コマンドラインパラメータを使用するか、デプロイコマンドを実行する環境で定義して、シークレットから DEPLOY_VAR_* 環境変数を置き換えます。

コマンドラインパラメータを使用して変数を置き換える

gcloud CLI デプロイコマンドは --substitutions 引数をサポートしています。これを使用して、パイプライン定義とデプロイ構成の変数をオーバーライドまたは設定できます。

コマンドラインパラメータを使用して変数を置き換えるには、コマンドラインで変数とその値のリストを指定します。

例:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local \
  --substitutions=VARIABLE_NAME_1=value_1,VARIABLE_NAME_2=value_2

代わりに、置換を YAML ファイルに保存し、--substitutions-file 引数で指定することもできます。

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local \
  --substitutions-file=substitutions.yaml

置換ファイルで、変数のマッピングを指定します。

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

パイプライン定義ファイルとデプロイ構成で変数名を使用できます。例: {{ VARIABLE_NAME_1 }}。

環境変数を使用して変数を指定して置き換える

パイプライン定義とデプロイ構成では、DEPLOY_VAR_ 接頭辞が付いた環境変数を使用できます。

環境変数を設定します。

export DEPLOY_VAR_VARIABLE_NAME_1=value_1

パイプライン定義ファイルとデプロイ構成で、変数名（DEPLOY_VAR_ 接頭辞なし）を使用できます。例: {{ VARIABLE_NAME_1 }}。

次のステップ

パイプラインを管理し、パイプライン実行の履歴とステータスを確認する