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

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

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

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

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

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

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

カスタムターゲットタイプのレンダリングとデプロイの方法を定義するタスク

カスタムレンダリングとカスタムデプロイの実装では、Cloud Deploy で指定された値を使用して、必要な出力のセットを完了する必要があります。

カスタムレンダリングは省略可能ですが、Cloud Deploy の組み込みレンダラでレンダリングされた場合にカスタムターゲットが正しく機能する場合を除いて、カスタムレンダリングを作成する必要があります。
カスタムターゲットタイプの定義

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

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

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

例

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

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

必要な入力と出力

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

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

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

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

詳細

カスタムレンダリングへの入力

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

CLOUD_DEPLOY_PROJECT

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

プロジェクトの Google Cloud プロジェクト ID。
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 機能のカンマ区切りのリスト。この変数には、配信パイプラインで構成された機能に基づいて値が設定されます。

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

標準デプロイの場合、これは空です。カナリアデプロイの場合、値は 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_DEPLOY_OUTPUT_GCS_PATH）で提供される 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_PROJECT_ID

プロジェクトの Google Cloud プロジェクト ID。
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 機能のカンマ区切りのリスト。この変数には、配信パイプラインで構成された機能に基づいて値が設定されます。

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

標準デプロイの場合、これは空です。カナリアデプロイの場合、値は 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 パス。リリースで Skaffold 構成を指定した場合。
CLOUD_DEPLOY_MANIFEST_GCS_PATH

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

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

カスタムデプロイからの出力

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

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

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

有効なステータスは次のとおりです。
- 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 クラスタで実行するようにタスクを構成することはできません。

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

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

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

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

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

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

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

カスタムターゲットの例

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

GitOps
Vertex AI
Terraform
Infrastructure Manager
Helm

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

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

次のステップ

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

カスタム ターゲットについて コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

例

必要な入力と出力

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

カスタム レンダリングへの入力

カスタム レンダリングからの出力