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

このドキュメントでは、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 機能を最大限に活用できます。

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

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

必要な入力と出力

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

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

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

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

カスタム ターゲットの入力として使用するデプロイ パラメータは、customTarget/ で始まる必要があります(例: customTarget/vertexAIModel)。デプロイ パラメータを環境変数として参照する場合は、次の構文を使用します。

CLOUD_DEPLOY_customTarget_[VAR_NAME]

ここで、VAR_NAME は、デプロイ パラメータ名のスラッシュに続く名前です。たとえば、customTarget/vertexAIModel という名前のデプロイ パラメータを定義する場合は、CLOUD_DEPLOY_customTarget_vertexAIModel として参照します。

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

カスタム レンダリング アクションの場合、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 機能のカンマ区切りのリスト。この変数は、デリバリー パイプラインで構成された機能に基づいて入力されます。

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

    標準デプロイの場合、これは空です。カナリア デプロイの場合、値は 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 ファイル。

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

      有効な値は SUCCEEDEDFAILED です。

    • (省略可)カスタム アクションによって生成されたエラー メッセージ。

    • レンダリングされた構成ファイルの 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 機能のカンマ区切りのリスト。この変数は、デリバリー パイプラインで構成された機能に基づいて入力されます。

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

    標準デプロイの場合、これは空です。カナリア デプロイの場合、値は 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)に配置する必要があります。

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

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

    有効なステータスは次のとおりです。

  • (省略可)デプロイ アーティファクト ファイルのリスト(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 は、カスタム レンダラと deployer がカナリア機能をサポートしている限り、カナリア デプロイをサポートします。

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

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

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

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

カスタム ターゲットの例

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

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

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

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

次のステップ