カスタム ターゲットを作成する

このドキュメントでは、カスタムの Cloud Deploy ターゲット タイプを作成し、Cloud Deploy デリバリー パイプラインでターゲットとしてそのカスタム ターゲット タイプを使用する方法について説明します。

カスタム ターゲット タイプを作成してデリバリー パイプラインで使用する大まかな手順は以下のとおりです。

  1. カスタム ターゲットにデプロイする機能を持ち、カスタム ターゲット タイプに関する Cloud Deploy の要件を満たすコンテナ化されたアプリケーションを作成します。

  2. skaffold.yaml で、そのコンテナを参照してコンテナ上で実行するコマンドを指定するカスタム アクションを定義します。

  3. 前のステップのカスタム アクションを参照する CustomTargetType 定義を作成して、Cloud Deploy リソースとして登録します。

  4. 新しいカスタム ターゲット タイプを識別する customTarget プロパティを持つ新しいターゲットを定義します。

  5. デリバリー パイプラインの進行に応じてそのターゲットを参照します。

  6. リリースを作成します。

これらの各ステップについては、以降で詳しく説明します。

コンテナ化されたアプリケーションを作成する

カスタム ターゲットにデプロイする機能は、コンテナ化されたアプリケーションで定義されます。コンテナ化されたアプリケーションは、skaffold.yaml ファイルから参照して Cloud Deploy に提供します。デリバリー パイプラインにカスタム ターゲット タイプを使用するターゲットが含まれている場合、Cloud Deploy は Skaffold でそのカスタム ターゲット タイプ用に定義されたカスタム アクション コンテナを呼び出して、定義したレンダリング アクションとデプロイ アクションを実行します。

アプリの動作は自由に決めることができます。ただし、Cloud Deploy で指定された入力環境変数を使用する必要があり、必要な出力を返す必要があります。

ほとんどの場合、作成するカスタム ターゲット タイプごとにレンダリング アクション用とデプロイ コンテナ用のコンテナを 1 つずつ作成します。レンダリング アクションは省略可能ですが、指定しない場合、Cloud Deploy はデフォルトの skaffold render を使用します。

Skaffold でカスタム アクションを定義する

カスタム アクション コンテナ イメージを配置したら、skaffold.yaml 構成ファイルから参照します。

カスタム ターゲットの各カスタム アクションは、customActions スタンザで構成します。どのカスタム ターゲット タイプでも、Skaffold でレンダリング用のカスタム アクションとデプロイ用のカスタム アクションを作成します。CustomTargetType 定義で、レンダリングに使用されるカスタム アクションとデプロイに使用されるカスタム アクションが識別されます。

skaffold.yaml でのカスタム レンダリングとデプロイ アクションの構成は次のとおりです。

apiVersion: skaffold/v4beta7
kind: Config
customActions:
# custom render action
- name:
  containers:
  - name:
    image:
    command:
    args:
# custom deploy action
- name:
  containers:
  - name:
    image:
    command:
    args:

この Skaffold 構成では:

  • customActions.name

    カスタム レンダリングまたはデプロイ アクションの名前は任意です。CustomTargetType 定義では、renderAction プロパティまたは deployAction プロパティでこの名前が参照されます。

  • containers スタンザには、実際の参照とそのコンテナを実行するコマンドが含まれています。

    containers スタンザでは複数のコンテナを使用できますが、1 つだけ使用することをおすすめします。

  • customActions.containers.name

    このアクションに使用する特定のコンテナの任意の名前です。ベスト プラクティスとして、このコンテナ名は常に SHA 修飾する必要があります。

  • image

    コンテナ イメージのパス。

  • command

    コンテナ上で実行するコマンドです。

  • args

    command の引数のコレクションです。

customActions で使用される構成プロパティの詳細なドキュメントについては、Skaffold YAML リファレンスをご覧ください。

カスタム ターゲット タイプを定義する

カスタム ターゲットを定義するには、まず CustomTargetType 構成を使用してカスタム ターゲット タイプを作成します。CustomTargetType は、デリバリー パイプラインの定義またはターゲット定義と同じファイルに作成できます。また、別のファイルに作成することもできます。

CustomTargetType の定義は次のとおりです。

# Custom target type config (preview)
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name: [CUSTOM_TARGET_TYPE_NAME]
  annotations:
  labels:
description:
customActions:
  renderAction: [RENDER_ACTION_NAME]
  deployAction: [DEPLOY_ACTION_NAME]
  includeSkaffoldModules:

ここで

  • CUSTOM_TARGET_TYPE_NAME

    このカスタム ターゲット タイプ定義に付ける任意の名前です。この名前は、定義しているカスタム ターゲット タイプを使用するターゲットのターゲット定義で参照されます。

  • RENDER_ACTION_NAME

    カスタム レンダリング アクションの名前。この値は、レンダリング アクションに対して skaffold.yaml で定義された customAction.name です。

  • DEPLOY_ACTION_NAME

    カスタム デプロイ アクションの名前です。この値は、デプロイ アクションに対して skaffold.yaml で定義された customAction.name です。

  • includeSkaffoldModules

    リモートの Skaffold 構成を使用している場合に使用する省略可能なスタンザです。このスタンザのプロパティは、リモート Skaffold 構成ファイルを使用するのセクションで説明されています。

リモートの Skaffold 構成ファイルを使用する

Skaffold 構成ファイルは、公開 Git リポジトリ、Cloud Storage バケット、Cloud Build 第 2 世代リポジトリに保存して、カスタム ターゲット タイプの定義から参照できます。

リモート Skaffold 構成ファイルを使用すると、リリース時に指定する skaffold.yaml にカスタム アクションを定義する必要がなくなることになります。これにより、組織全体でカスタム アクションを共有できます。

リモートの Skaffold 構成ファイルを使用するには:

  1. カスタム アクションを使用して Skaffold 構成を作成します。

  2. その構成を Git リポジトリまたは Cloud Storage バケットに保存します。

  3. カスタム ターゲット タイプの定義に customActions.includeSkaffoldModules スタンザを追加します。

  4. includeSkaffoldModules で次のように指定します。

    • 必要に応じて、1 つ以上の configs 要素:

      - configs: ["name1", "name2"]

      configs の値は、含める各 Skaffold 構成ファイルの metadata.name プロパティに一致する文字列のリストです。これを省略すると、Cloud Deploy は指定されたパス内のすべての構成ファイルを取得します。

    • googleCloudStorage、git、googleCloudBuildRepo スタンザのいずれか。

      Cloud Storage の場合:

      googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME

      Git の場合:

      git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      Cloud Build リポジトリ（第 2 世代）の場合:

       googleCloudBuildRepo:
  repository: PATH_TO_GCB_REPO
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      ここで

      PATH_TO_GCS_BUCKET は、/* で終わる Cloud Storage ディレクトリのパスで、そこに Skaffold 構成ファイルが保存されます。Skaffold により、このディレクトリ内のすべてのファイルがダウンロードされ、構成された相対パスに基づいて、構成ファイルを含む関連する Skaffold ファイルが検出されます。

      PATH_TO_GCB_REPO は、Skaffold 構成ファイルが格納されている Cloud Build 第 2 世代リポジトリへのパスです。パスの形式は projects/{project}/locations/{location}/connections/{connection}/repositories/{repository} です。Skaffold により、このディレクトリ内のすべてのファイルがダウンロードされ、構成された相対パスに基づいて Skaffold ファイルが検出されます。

      FILENAME は、Skaffold 構成ファイルを含むファイルの名前です。この path: プロパティは省略可能です。指定しない場合、Cloud Deploy は skaffold.yaml を前提とします。skaffold.yaml が存在しない場合または指定したファイル名が存在しない場合、リリースの作成は失敗します。

      REPO_URL は Git リポジトリの URL です。

      PATH_TO_FILE は、Skaffold 構成ファイルを含むファイルへのリポジトリのパスです。

      BRANCH_NAME は、Skaffold 構成を取得するブランチの名前（main など）です。

例

次のカスタム ターゲット タイプの YAML は、customActions スタンザに includeSkaffoldModules スタンザを加えたもので、Cloud Storage バケットに保存された Skaffold 構成ファイルを指しています。

customActions:
  renderAction: my-custom-action
  deployAction: my-custom-action
  includeSkaffoldModules:
    - configs: ["myConfig"]
      googleCloudStorage:
        source: "gs://my-custom-target-bucket/my-custom/*"
        path: "skaffold.yaml

次の YAML は Skaffold 構成ファイルで、表示されているカスタム アクションが参照しています。

apiVersion: skaffold/v4beta7
kind: Config
metadata:
  name: myConfig
customActions:
  - name: my-custom-action
    containers:
      - name: my-custom-container
        image: us-east1-docker.pkg.dev/abcdefg/foldername/myimage@sha256:c56fcf6e0a7637ddf0df3d56a0dd23bfce03ceca06a6fc527b0e0e7430e6e9f9

カスタム ターゲット タイプを登録する

CustomTargetType を構成したら、gcloud deploy apply コマンドを実行して、Google Cloud プロジェクトに CustomTargetType リソースを登録します。

gcloud deploy apply --file=[FILE] --project=[PROJECT] --region=[REGION]

ここで

FILE は、このカスタム ターゲット タイプを定義したファイルの名前です。

PROJECT は、このリソースを作成する Google Cloud プロジェクトです。CustomTargetType は、それを参照する Target リソースと同じプロジェクトに存在する必要があります。Google Cloud CLI のデフォルト プロジェクトとして設定している場合は、プロジェクトを指定する必要はありません。

REGION は、このリソースを作成するリージョン（us-centra1 など）です。CustomTargetType は、それを参照する Target リソースと同じリージョンに存在する必要があります。リージョンを gcloud CLI のデフォルト リージョンとして設定している場合は、リージョンを指定する必要はありません。

CustomTargetType が Cloud Deploy リソースとして作成されたので、それを Target 定義で使用してカスタム ターゲットを作成できるようになりました。

CustomTargetType 定義の詳細については、Cloud Deploy 構成スキーマ リファレンスをご覧ください。

ターゲットを定義する

サポートされているターゲット タイプのターゲット定義とカスタム ターゲット定義の唯一の違いは、カスタム ターゲット定義に customTarget スタンザが含まれていることです。customTarget の構文は次のとおりです。

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

ここで、CUSTOM_TARGET_TYPE_NAME は、カスタム ターゲット タイプの構成で定義された name プロパティの値です。

配信パイプラインにターゲットを追加する

カスタム ターゲットは、サポートされているターゲット タイプを使用する場合とまったく同じようにデリバリー パイプラインで使用できます。つまり、サポートされているターゲット タイプとカスタム ターゲットのターゲット間で、デリバリー パイプラインの進行に違いはありません。

デリバリー パイプライン内のターゲットはすべて同じターゲット タイプを使用する必要があります。たとえば、Google Kubernetes Engine にデプロイするターゲットとカスタム ターゲットを持つデリバリー パイプラインは使用できません。

サポートされているターゲット タイプと同様に、パイプライン ステージにデプロイ パラメータを含めることができます。

リリースを作成する

カスタム ターゲット タイプを完全に定義し、そのタイプを使用するターゲットが作成されると、通常の方法でリリースを作成できるようになります。

gcloud deploy releases create [RELEASE_NAME] \
  --project=[PROJECT_NAME] \
  --region=[REGION] \
  --delivery-pipeline=[PIPELINE_NAME]

リリースを作成すると、リリース、ターゲット、デリバリーのいずれかのパイプラインで構成されたデプロイ パラメータの処理を含む、デリバリー パイプラインの各ターゲットに対してカスタム レンダリング アクションが実行されます。Cloud Deploy により、カスタム レンダリング コンテナへの入力としてデプロイ パラメータが提供されます。

カスタム ターゲットの出力を表示する

カスタム アクションがカスタム ターゲットの要件を満たしている場合、Google Cloud コンソールを使用してレンダリングされたアーティファクトを表示できます。

カスタム レンダリング アクションの出力を表示する手順は以下のとおりです。

  1. Google Cloud コンソールで、Cloud Deploy の [デリバリー パイプライン] ページに移動して、デリバリー パイプラインを表示します。

    [デリバリー パイプライン] ページを開く

  2. デリバリー パイプラインの名前をクリックします。

    パイプラインの可視化によりアプリのデプロイ ステータスが表示され、[デリバリー パイプラインの詳細] の [リリース] タブにリリースが一覧表示されます。

  3. リリース名をクリックします。

    [リリースの詳細] ページが表示されます。

  4. [アーティファクト] タブをクリックします。

  5. [ターゲットのアーティファクト] で、[アーティファクトを表示] の横にある矢印をクリックします。

    レンダリングされたアーティファクト（レンダリングされた skaffold.yaml やカスタム レンダラによって生成されたレンダリング マニフェスト ファイルなど）が一覧表示されます。また、各ファイルの横にある [ストレージの場所] リンクをクリックすると、Cloud Storage バケットに移動してこれらのファイルを表示できます。

    [アーティファクトを表示] リンクをクリックすると、リリース インスペクタを使用して、リリース別、ターゲット別、フェーズ別にファイルを表示することもできます。

次のステップ