このページは Cloud Translation API によって翻訳されました。

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

このドキュメントでは、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_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 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 パス。
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 クラスタで実行するようにカスタムアクションを構成することはできません。

リモートの再利用可能な 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 の実行環境について学習する。

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

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

例

必要な入力と出力

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

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

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