カスタムターゲットについて

このドキュメントでは、Cloud Deploy におけるカスタムターゲットの仕組みについて説明します。

Cloud Deploy には、さまざまなランタイム環境のサポートがターゲットとして組み込まれています。ただし、サポート対象のターゲットタイプのリストには上限があります。カスタムターゲットを使用すると、サポート対象のランタイム以外のシステムにもデプロイできます。

カスタムターゲットとは、Cloud Deploy でサポートされるランタイム以外の任意の出力環境を表すターゲットです。

カスタムターゲットタイプを定義し、デリバリーパイプラインでターゲットとして実装するプロセスは、カスタムターゲットを作成するページで説明されています。

カスタムターゲットの内容

各カスタムターゲットは、以下のコンポーネントで構成されています。

カスタムアクション（skaffold.yaml で定義）

これらは、デプロイフックの定義方法と似ています。skaffold.yaml ファイルでは customActions を定義します。そこで、各カスタムアクションで使用するコンテナイメージとそのコンテナ上で実行するコマンドが特定されます。

このように、カスタムターゲットは単にカスタム定義されたアクション（アクションのセット）です。

どのカスタムターゲットタイプでも、カスタムレンダリングアクションとカスタムデプロイアクションを構成します。これらのアクションは Cloud Deploy で指定された値を使用して、必要な出力のセットを完了する必要があります。

カスタムレンダリングアクションはオプションですが、Cloud Deploy のデフォルトである skaffold render によってレンダリングされた場合は、カスタムターゲットが正しく機能する場合を除いて、カスタムレンダリングアクションを作成する必要があります。
カスタムターゲットタイプの定義

CustomTargetType は、このタイプのターゲットがリリースレンダリングとロールアウトデプロイアクティビティに使用するカスタムアクション（skaffold.yaml で個別に定義）を識別する Cloud Deploy リソースです。
ターゲット定義

カスタムターゲットのターゲット定義は、値が CustomTargetType の名前である customTarget プロパティを含むことを除いて、どのターゲットタイプでも同じです。

これらのコンポーネントを適正に配置すると他のターゲットと同じようにそのターゲットを使用し、デリバリーパイプラインの進行に応じてターゲットを参照して、プロモーションと承認、ロールバックなどの Cloud Deploy 機能を最大限に活用できます。

例

クイックスタートのカスタムターゲットタイプを定義して使用するでは、コンテナイメージで実行する簡単なコマンド（レンダリング用とデプロイ用の 1 つずつ）を含むカスタムターゲットタイプを作成します。この場合のコマンドは、レンダリングとデプロイに必要な出力ファイルにテキストを追加するだけです。

その他の例については、カスタムターゲットの例をご覧ください。

必要な入力と出力

Cloud Deploy で定義されたカスタムターゲットタイプは、レンダリングとデプロイの両方で入力と出力の要件を満たす必要があります。このセクションでは、必要となる入出力とその指定方法を示します。

Cloud Deploy では、レンダリングとデプロイの両方で必要な入力が環境変数として提供されます。この後のセクションでは、これらの入力と、カスタムレンダリングとデプロイのアクションで返される必要がある出力を示します。

パラメータを環境変数としてデプロイする

このセクションに記載されている環境変数に加えて、設定したデプロイパラメータが Cloud Deploy からカスタムコンテナに渡されます。

詳細。

レンダリングアクションの入力

カスタムレンダリングアクションの場合、Cloud Deploy では次の必須入力が環境変数として提供されます。マルチフェーズロールアウト（カナリアデプロイ）の場合、Cloud Deploy では以下の変数が各フェーズで提供されます。

CLOUD_DEPLOY_PROJECT

カスタムターゲットタイプが作成される Google Cloud プロジェクト。
CLOUD_DEPLOY_LOCATION

カスタムターゲットタイプの Google Cloud リージョン。
CLOUD_DEPLOY_DELIVERY_PIPELINE

カスタムターゲットタイプを使用するターゲットを参照する Cloud Deploy のデリバリーパイプラインの名前。
CLOUD_DEPLOY_RELEASE

レンダリングオペレーションが呼び出されるリリースの名前。
CLOUD_DEPLOY_TARGET

カスタムターゲットタイプを使用する Cloud Deploy ターゲットの名前。
CLOUD_DEPLOY_PHASE

レンダリングに対応するロールアウトフェーズ。
CLOUD_DEPLOY_REQUEST_TYPE

カスタムレンダリングアクションの場合、これは常に RENDER です。
CLOUD_DEPLOY_FEATURES

カスタムコンテナがサポートする必要がある Cloud Deploy 機能のカンマ区切りのリスト。この変数は、配信パイプラインで構成された特徴に基づいて入力されます。

実装上このリストの機能がサポートされていない場合は、レンダリングでエラーにすることをおすすめします。

標準デプロイの場合、これは空です。カナリア Deployment の場合、値は CANARY です。Cloud Deploy で指定された値が CANARY の場合、カナリアの各フェーズでレンダリングアクションが呼び出されます。各フェーズのカナリアパーセンテージは CLOUD_DEPLOY_PERCENTAGE_DEPLOY 環境変数で指定されます。
CLOUD_DEPLOY_PERCENTAGE_DEPLOY

このレンダリングオペレーションに関連するデプロイの割合。CLOUD_DEPLOY_FEATURES 環境変数が CANARY に設定されている場合、フェーズごとにカスタムレンダリングアクションが呼び出され、この変数が各フェーズのカナリアパーセンテージに設定されます。標準デプロイと stable フェーズに到達したカナリアデプロイの場合、これは 100 です。
CLOUD_DEPLOY_STORAGE_TYPE

ストレージプロバイダ常に GCS です。
CLOUD_DEPLOY_INPUT_GCS_PATH

リリースの作成時に書き込まれたレンダーファイルアーカイブの Cloud Storage パス。
CLOUD_DEPLOY_OUTPUT_GCS_PATH

カスタムレンダリングコンテナがデプロイで使用されるアーティファクトをアップロードする際に想定される Cloud Storage のパス。レンダリングアクションは、このレンダリングオペレーションの結果を含む results.json という名前のファイルをアップロードする必要があります。詳細については、レンダリングアクションからの出力をご覧ください。

レンダリングアクションからの出力

カスタムレンダリングアクションでは、このセクションで説明する情報が提供される必要があります。その情報は、Cloud Deploy で提供される Cloud Storage バケットにある results.json という名前の結果ファイルに含める必要があります。

レンダリングされた構成ファイル
以下の情報が含まれている results.json ファイル。
- カスタムアクションの成功または失敗の状態を示す表示。
  
  有効な値は SUCCEEDED と FAILED です。
- （省略可）カスタムアクションによって生成されたエラーメッセージ。
- レンダリングされた構成ファイルの Cloud Storage パス。
  
  レンダリングされたすべての構成ファイルのパスには、完全な URI が使用されます。Cloud Deploy によって提供される CLOUD_DEPLOY_OUTPUT_GCS_PATH の値を部分的に使用して入力します。
  
  レンダリングされた構成ファイルは、空であっても指定する必要があります。ファイルの内容は、カスタムデプロイアクションで使用できるものであれば、どのような形式でもかまいません。このファイルは、お客様や組織内の別のユーザーがリリースインスペクタでこのファイルを表示できるように、人が読める形式にすることをおすすめします。
- （省略可）含めるメタデータのマップ
  
  このメタデータはカスタムターゲットによって作成されます。このメタデータは、本リリースの custom_metadata フィールドに保存されます。

デバッグなどのために results.json ファイルを調べる必要がある場合は、Cloud Build ログでそのファイルの Cloud Storage URI を確認できます。

レンダリング結果ファイルの例

カスタムレンダリングアクションから出力される results.json ファイルの例を次に示します。

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

デプロイアクションの入力

カスタムデプロイアクションの場合、Cloud Deploy では次の必須入力が環境変数として提供されます。

CLOUD_DEPLOY_PROJECT

カスタムターゲットが作成される Google Cloud プロジェクト。
CLOUD_DEPLOY_LOCATION

カスタムターゲットタイプの Google Cloud リージョン。
CLOUD_DEPLOY_DELIVERY_PIPELINE

カスタムターゲットタイプを使用するターゲットを参照する Cloud Deploy のデリバリーパイプラインの名前。
CLOUD_DEPLOY_RELEASE

デプロイオペレーションが呼び出されるリリースの名前。
CLOUD_DEPLOY_ROLLOUT

このデプロイの対象となる Cloud Deploy のロールアウトの名前。
CLOUD_DEPLOY_TARGET

カスタムターゲットタイプを使用する Cloud Deploy ターゲットの名前。
CLOUD_DEPLOY_PHASE

デプロイに対応するロールアウトフェーズ。
CLOUD_DEPLOY_REQUEST_TYPE

カスタムデプロイアクションの場合、これは常に DEPLOY です。
CLOUD_DEPLOY_FEATURES

カスタムコンテナがサポートする必要がある Cloud Deploy 機能のカンマ区切りのリスト。この変数は、配信パイプラインで構成された特徴に基づいて入力されます。

実装上このリストの機能がサポートされていない場合は、レンダリングでエラーにすることをおすすめします。

標準デプロイの場合、これは空です。カナリア Deployment の場合、値は CANARY です。Cloud Deploy で指定された値が CANARY の場合、カナリアの各フェーズでレンダリングアクションが呼び出されます。各フェーズのカナリアパーセンテージは CLOUD_DEPLOY_PERCENTAGE_DEPLOY 環境変数で指定されます。
CLOUD_DEPLOY_PERCENTAGE_DEPLOY

このデプロイオペレーションに関連するデプロイの割合。CLOUD_DEPLOY_FEATURES 環境変数が CANARY に設定されている場合、フェーズごとにカスタムデプロイアクションが呼び出され、この変数が各フェーズのカナリアパーセンテージに設定されます。デプロイアクションはフェーズごとに実行する必要があります。
CLOUD_DEPLOY_STORAGE_TYPE

ストレージプロバイダ常に GCS です。
CLOUD_DEPLOY_INPUT_GCS_PATH

カスタムレンダラがレンダリング構成ファイルを書き込んだ Cloud Storage パス。
CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

レンダリングされた Skaffold 構成の Cloud Storage パス。
CLOUD_DEPLOY_MANIFEST_GCS_PATH

レンダリングされたマニフェストファイルの Cloud Storage パス。
CLOUD_DEPLOY_OUTPUT_GCS_PATH

カスタムデプロイコンテナがデプロイアーティファクトをアップロードすると予想される Cloud Storage ディレクトリのパス。詳細については、デプロイアクションの出力をご覧ください。

デプロイアクションからの出力

カスタムデプロイアクションは、results.json 出力ファイルを書き込む必要があります。このファイルは、Cloud Deploy によって提供される Cloud Storage バケット（CLOUD_DEPLOY_OUTPUT_GCS_PATH）に配置する必要があります。

このファイルには、以下のものが含まれている必要があります。

カスタムデプロイアクションの成功または失敗の状態を示す表示。

有効なステータスは次のとおりです。
- SUCCEEDED
- FAILED
- SKIPPED（カナリアフェーズがスキップされ、そのまま stable に進むカナリアデプロイの場合）
（省略可）デプロイアーティファクトファイルのリスト（Cloud Storage パスの形式）

パスは完全 URI です。Cloud Deploy によって提供される CLOUD_DEPLOY_OUTPUT_GCS_PATH の値を部分的に使用して入力します。

ここに一覧表示されたファイルは、デプロイアーティファクトとしてジョブ実行リソースに入力されます。
（省略可）カスタムデプロイアクションが成功しなかった場合（FAILED 状態を返した場合）は失敗メッセージ

このメッセージは、このデプロイアクションのジョブ実行時に failure_message を入力するために使用されます。
（省略可）アクションによって SKIPPED ステータスが返された場合に、追加情報を提供するスキップメッセージ。
（省略可）含めるメタデータのマップ

このメタデータはカスタムターゲットによって作成されます。このメタデータは、ジョブ実行時とロールアウト時に custom_metadata フィールドに格納されます。

デバッグなどのために results.json ファイルを調べる必要がある場合は、Cloud Build リリースレンダリングログでそのファイルの Cloud Storage URI を確認できます。

デプロイ結果ファイルの例

カスタムデプロイアクションから出力される results.json ファイルの例を次に示します。

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

カスタムアクションの詳細

カスタムターゲットタイプを設定して使用する際は、次の点に留意してください。

カスタム操作の実行

カスタムレンダリングアクションとカスタムデプロイアクションは、Cloud Deploy の実行環境で実行されます。Google Kubernetes Engine クラスタで実行するようにカスタムアクションを構成することはできません。

リモートで再利用可能な Skaffold 構成を使用する

このドキュメントで説明するように、カスタムアクションはリリース作成時に提供される skaffold.yaml ファイルで構成します。ただし、Skaffold 構成ファイルを Git リポジトリまたは Cloud Storage バケットに保存して、カスタムターゲットタイプ定義から参照することもできます。これにより、各リリースの skaffold.yaml ファイルにカスタムアクションを含めるのではなく、単一の共有ロケーションに定義して保存したカスタムアクションを使用できます。

カスタムターゲットとデプロイの戦略

カスタムターゲットは、標準のデプロイで完全にサポートされています。

カスタムレンダラとデプロイツールがカナリア機能をサポートしている限り、Cloud Deploy はカナリアデプロイをサポートします。

カスタムカナリア構成を使用する必要があります。自動カナリアおよびカスタム自動カナリアはサポートされていません。

カスタムターゲットとデプロイパラメータ

カスタムターゲットではデプロイパラメータを使用できます。デプロイパラメータは、デリバリーパイプラインステージ、カスタムターゲットタイプを使用するターゲット、リリースで設定できます。

デプロイパラメータは、すでに提供された環境変数に加えて、カスタムレンダリングおよびデプロイコンテナに環境変数として渡されます。

カスタムターゲットの例

cloud-deploy-samples リポジトリには、カスタムターゲット実装のサンプルセットが含まれています。次のサンプルを使用できます。

GitOps
Vertex AI
Terraform
Infrastructure Manager
Helm

各サンプルにはクイックスタートが含まれています。

これらのサンプルは、サポート対象の Google Cloud プロダクトではなく、Google Cloud サポート契約の対象外です。Google Cloud プロダクトのバグを報告する場合や、機能をリクエストする場合は、Google Cloud サポートにお問い合わせください。

次のステップ

カスタムターゲットがわかったところで、カスタムターゲットの構成と使用の方法を確認する。
クイックスタート「カスタムターゲットタイプを定義して使用する」を試す
詳しくは、Cloud Deploy ターゲットの構成をご覧ください。
Cloud Deploy の実行環境について学習する。

カスタム ターゲットについて

カスタム ターゲットの内容

例

必要な入力と出力

パラメータを環境変数としてデプロイする

レンダリング アクションの入力

レンダリング アクションからの出力