デプロイにパラメータを渡す

Cloud Deploy を使用すると、リリースのパラメータを渡し、それらの値をマニフェストに提供してから、マニフェストをそれぞれのターゲットに適用できます。この置換は、Cloud Deploy レンダリング オペレーションの最終ステップとして、マニフェストがrendered後に行われます。値は、対応するプレースホルダを含む skaffold.yaml ファイルで特定されたすべてのマニフェストに提供されます。

行う必要があるのは、マニフェストにプレースホルダを追加し、Cloud Deploy デリバリー パイプラインまたはターゲット構成で、またはリリースの作成時にプレースホルダの値を設定することのみです。

この記事では、その方法について説明します。

デプロイ パラメータを使用する理由

通常、このパラメータは並列デプロイ内の異なるターゲットのマニフェストに異なる値を適用するために使用されます。ただし、マニフェストでレンダリング後の Key-Value ペアの置換が必要なものには、デプロイ パラメータを使用できます。

手続きの流れ

次の手順では、デプロイ パラメータを構成して値を指定する一般的なプロセスについて説明します。

1. こちらの説明に沿って、デプロイのパラメータ化を構成します。

   これには次のものが含まれます。

   • プレースホルダをマニフェストに追加します。各プレースホルダのデフォルト値も追加します。

   • これらのプレースホルダに値を追加します。

     これを行うには 3 つの方法があり、こちらで説明しています。

2. リリースを作成すると、マニフェストがrenderedされます。

   テンプレート化されたマニフェストから開始した場合は、テンプレート変数に値が適用されます。未加工のマニフェストから開始した場合は、変更されません。このレンダリングは Skaffold によって行われます。

   ただし、レンダリング時に値が適用されない追加の変数をマニフェストに設定できます。これらは、このドキュメントで説明するデプロイ パラメータです。

   リリースの作成時に、すべてのデプロイ パラメータが辞書にコンパイルされ、マニフェストが適用される前に値の置換に使用されます。

   注: 指定されたデプロイ パラメータ（キー）に複数の値が割り当てられている場合、リリースは失敗します。

3. レンダリング後、Cloud Deploy はデプロイ パラメータの値を置き換えます。

   これらは、最初の手順で構成した値です。

   レンダリング プロセスでは、すでにマニフェスト テンプレートに値が適用されており、一部の値が置換され、Cloud Deploy に固有のラベルが追加されます。ただし、これらのデプロイ パラメータの値はレンダリング後に置き換えられます。マニフェスト テンプレートとデプロイ パラメータの違いについては、こちらをご覧ください。

4. マニフェストはターゲット ランタイムに適用され、アプリケーションをデプロイします。

   これには、レンダリング時に置き換えられた値と、デプロイ パラメータの値が含まれます。

値を渡すさまざまな方法

パラメータとその値を指定する方法は 3 つあります。

• デリバリー パイプラインの定義で

  パラメータとその値は、配信パイプラインの進行状況のステージの定義で指定します。パラメータは、そのステージで表されるターゲットに渡されます。対象のステージでマルチターゲットを参照している場合は、ここで設定した値がすべての子ターゲットに使用されます。

  このメソッドを使用すると、特定のパイプライン内に存在する影響を受けるすべてのターゲットのすべてのリリースの値を置き換えることができます。ステージに対して定義されたパラメータはラベルを識別し、そのステージの対応するターゲットには一致するラベルが必要です。

• ターゲットの定義内で

  パラメータとその値は、ターゲット自体の定義で構成します。このメソッドを使用すると、すべてのリリースで対象のターゲットの値を置換できます。

• リリースを作成する際にコマンドラインで

  gcloud deploy releases create コマンドで --deploy-parameters フラグを使用して、パラメータとその値を追加します。

  この方法では、リリースの作成時に値を置換し、その値を、影響を受けるすべてのターゲットのマニフェストに適用できます。

これらの構成の詳細については、こちらをご覧ください。

これらの方法のうち複数を使用できますか？

はい。パイプライン ステージ、ターゲット構成、コマンドラインにデプロイ パラメータを配置できます。その結果、すべてのパラメータが受け入れられ、辞書に追加されます。ただし、特定のパラメータが複数の場所で渡されたものの、値が異なる場合、gcloud deploy releases create コマンドはエラーで失敗します。

マニフェスト テンプレートとの違い

この記事で説明するデプロイ パラメータは、テンプレート化されたマニフェストのプレースホルダと構文で区別されます。ただし、テンプレート化されたマニフェストの標準手法を使用する代わりに、デプロイ パラメータが必要な理由について疑問に思われる場合は、次の表にさまざまな目的を示しています。

技術	交代時間	対象
マニフェスト テンプレート	レンダリング フェーズ	特定のリリース。特定のターゲット
コマンドラインで	レンダリング後	特定のリリース。すべてのターゲット
デリバリー パイプラインで	レンダリング後	すべてのリリース。特定のターゲット（ラベル別）
ターゲットで	レンダリング後	すべてのリリース。特定のターゲット

このドキュメントでは、テンプレート マニフェストではなく、デプロイ パラメータ（コマンドライン、パイプライン、ターゲット）についてのみ説明します。

制限事項

• パラメータのタイプごとに、最大 50 個のパラメータを作成できます。

• 子ターゲットは、さらに親マルチターゲットから最大 50 個のパラメータを継承でき、ターゲットに最大 200 個のパラメータ（パイプラインのステージで設定されたパラメータを含む）を作成できます。

• キー名は、最大 63 文字の文字数と、次の正規表現に制限されます。

  ^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$
  

  ただし、カスタム ターゲットでデプロイ パラメータを環境変数として使用する場合は、キーワード customTarget と変数名（customTarget/VAR_NAME）の間にスラッシュを使用する必要があります。サポートされている構文については、必要な入出力をご覧ください。

• 接頭辞 CLOUD_DEPLOY_ は予約されているため、キー名に使用できません。

• 同じターゲットに 2 つの同じ名前のキーを適用することはできません。

• この値は空にできますが、最大 512 文字の制限があります。

• デプロイ パラメータのプレースホルダは Helm 構成値には使用できませんが、慣例に従って渡す必要があります。

デプロイ パラメータを構成する

このセクションでは、Kubernetes マニフェスト、Cloud Run サービス、または Helm テンプレートに適用されるデプロイ パラメータ値を構成する方法について説明します。

このセクションで説明するように、これらの Key-Value ペアを構成するだけでなく、1 つまたは複数のプレースホルダをマニフェストに追加する必要があります。

マニフェストにプレースホルダを追加する

Kubernetes マニフェスト（GKE の場合）またはサービス YAML（Cloud Run の場合）で、レンダリング後に置き換える値のプレースホルダを追加します。

構文

Skaffold で Helm レンダラを使用していないリリースでは、プレースホルダに次の構文を使用します。

[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}

この行では...

• PROPERTY:

  Kubernetes マニフェストまたは Cloud Run サービス YAML の構成プロパティです。

• DEFAULT_VALUE

  コマンドライン、パイプライン、ターゲット構成でこのプロパティに値が指定されていない場合に使用する値です。デフォルト値は必須ですが、空の文字列（""）にできます。

• # from-param:

  コメント文字を使用して Cloud Deploy deploy-parameters ディレクティブをオフに設定し、from-param: は Cloud Deploy に対して deploy-parameters プレースホルダが後置されることを伝えます。

• ${VAR_NAME}

  置換するプレースホルダ。これは、デリバリー パイプラインまたはターゲット構成で、あるいはリリースの作成時に指定された Key-Value ペアのキーと一致する必要があります。

1 行に複数のパラメータを使用したり、パラメータを長い文字列の一部として使用したりすることもできます。例:

image: my-image # from-param: ${artifactRegion}-docker.pkg.dev/my-project/my-repo/my-image@sha256:${imageSha}

これらのパラメータは複数のソースから取得できます。前の例では、${artifactRegion} はターゲットまたはデリバリー パイプラインのステージで定義され、${imageSha} はリリースの作成時にコマンドラインから取得されます。

Helm チャート値のパラメータ

構成値を受け入れる Helm チャートをレンダリングし、デプロイ パラメータを使用してこれらの値を設定する場合、デプロイ パラメータには、設定する Helm 構成値と一致する名前を付ける必要があります。すべてのデプロイ パラメータは、レンダリング時に --set 引数として Helm に渡されます。skaffold.yaml の変更は必要ありません。

たとえば、skaffold.yaml で、webserver.port の構成パラメータを取得する Helm チャートをインストールして、ウェブサーバーを起動するポートを指定し、これをデプロイ パラメータから動的に設定する場合は、webserver.port という名前とウェブサーバー ポートに必要な値でデプロイ パラメータを作成する必要があります。

したがって、skaffold.yaml で Helm テンプレートを参照するだけでなく、それらのテンプレートを作成する場合、Helm テンプレートで {{ .Values.VAR_NAME }} の標準 Helm 変数構文を利用できます。

たとえば、webserver.port で構成されたデプロイ パラメータがある場合は、次のように利用できます。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webserver
spec:
  replicas: 3
  selector:
    matchLabels:
      app: webserver
  template:
    metadata:
      labels:
        app: webserver
    spec:
      containers:
      - name: webserver
        image: gcr.io/example/webserver:latest
        ports:
        - containerPort: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
          name: web
        env:
        - name: WEBSERVER_PORT
          value: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.

パイプライン ステージにパラメータを追加する

配信パイプラインの進行状況のステージに Key-Value ペアを追加できます。これは、並列デプロイで子ターゲットを区別する場合に有効です。

1. こちらの説明に沿って、Kubernetes マニフェストまたは Cloud Run サービスにプレースホルダを追加します。

   次に例を示します。

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    replicas: 1 # from-param: ${deploy_replicas}
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
          - containerPort: 80
   

2. 該当するパイプライン ステージに deployParameters を含めるようにデリバリー パイプラインを構成します。

   次の YAML は、ターゲットがマルチターゲット（この場合は 2 つの子ターゲットが設定されている）のパイプライン ステージの構成です。

   serialPipeline:
    stages:
      - targetId: dev
        profiles: []
      - targetId: prod  # multi-target
        profiles: []
        deployParameters:
          - values:
              deploy_replicas: 1
              log_level: "NOTICE"
            matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
              my-app: "post-render-config-1"
          - values:
              deploy_replicas: 2
              log_level: "WARNING"
            matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
              my-app: "post-render-config-2"
   

   このデリバリー パイプラインの構成では、deployParameters スタンザには 2 つの values が含まれ、それぞれに以下の対象が設定されています。

   • 変数名。マニフェストで設定した変数と同じ名前です。

   • 変数の値

   • ターゲット固有のラベルと照合する 1 つ以上のラベル（省略可）

     matchTargetLabels スタンザでラベルを指定しない場合、その値はステージ内のすべてのターゲットに使用されます。

3. matchTargetLabels を指定した場合は、照合するためのラベルをターゲットに設定する必要もあります。このようにして、どの値をどの子ターゲットに割り当てるかを特定します。

   ターゲットは、values スタンザに設定されているすべてのラベルと一致する必要があります。

   matchTargetLabels を省略すると、パイプラインに設定した values がすべての子ターゲットに適用されます。ただし、同じパラメータに複数の値を設定すると、リリースは失敗します。

各マニフェストがレンダリングされると、Cloud Deploy は各変数の値をレンダリングされたマニフェストに追加します。

ターゲット構成にパラメータを追加する

Key-Value ペアをターゲットに追加できます。デプロイ パラメータを使用して複数の子ターゲットを区別する場合は、マルチターゲットではなく、これらの子ターゲットでデプロイ パラメータを構成します。

1. デプロイ時に設定する値の代わりにパラメータを使用して、Kubernetes マニフェストまたは Cloud Run サービス定義を構成します。

   次に例を示します。

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
          env:
          - name: envvar1
            value: example1 # from-param: ${application_env1}
          - name: envvar2
            value: example2 # from-param: ${application_env2}
   

   このマニフェストでは、パラメータ envvar1 はデフォルトの example1 に設定され、パラメータ envvar2 はデフォルトの example2 に設定されています。

2. deployParameters を含めるようにターゲットを構成します。

   含めるパラメータごとに、次の項目を指定します。

   • キー名。マニフェストで設定したキー（変数）と同じ名前です。

   • そのキーの値。値を指定しない場合は、マニフェストで設定されたデフォルト値が使用されます。

   次の YAML は、2 つのターゲットの構成です。各ターゲットには、値を設定する deployParameters スタンザが含まれています。各ターゲットには、パイプライン ステージで構成されたデプロイ パラメータと照合されるラベルも含まれています。

   apiVersion: deploy.cloud.google.com/v1beta1
   kind: Target
   metadata:
     name: prod1
     labels:
       my-app: "post-render-config-1"
   description: development cluster
   deployParameters:
     application_env1: "newValue1"
   ---
   
   apiVersion: deploy.cloud.google.com/v1beta1
   kind: target
   metadata:
     name: prod2
     labels:
       my-app: "post-render-config-2"
   description: development cluster
   deployParameters:
     application_env1: "newValue2"
   

リリースを作成するときに、マニフェストがレンダリングされた後で、Cloud Deploy ではレンダリングされたマニフェストにこれらの値が追加されます（関連するキーが含まれている場合）。

リリースの作成時にパラメータを渡す

リリースにパラメータと値を渡す手順は次のとおりです。

1. デプロイ時に設定する値の代わりにパラメータを使用して、Kubernetes マニフェストまたは Cloud Run サービス定義を構成します。

   次に例を示します。

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      annotations:
        commit: defaultShaValue # from-param: ${git-sha}
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
   

   この例では、コミット SHA が ${git-sha} という変数として設定されています。この値は、次の手順で示すように、--deploy-parameters= オプションを使用してリリース作成時に渡されます。

   この変数の構文は、$ と、中かっこに囲われた変数名になります。この例では ${git-sha} です。

2. リリースを作成する場合は、gcloud deploy releases create コマンドに --deploy-parameters オプションを配置します。

   --deploy-parameters は、Key-Value ペアのカンマ区切りのリストを受け取ります。ここで、キーはマニフェストに追加したプレースホルダです。

   コマンドは次のようになります。

   gcloud deploy releases create test-release-001 \
   --project=my-example-project \
   --region=us-central1 \
   --delivery-pipeline=my-params-demo-app-1 \
   --images=my-app-image=gcr.io/google-containers/nginx@sha256:f49a843c290594dcf4d193535d1f4ba8af7d56cea2cf79d1e9554f077f1e7aaa \
   --deploy-parameters="git-sha=f787cac"
   
   

リリースが作成する際に、マニフェスト レンダリング後に、関連するキーが含まれている場合、Cloud Deploy はレンダリングされたマニフェストに値を指定します。

カスタム ターゲットを使用してパラメータをデプロイする

カスタム ターゲットでは、任意のデプロイ パラメータを環境変数として使用できます。その場合は、カスタム ターゲットに指定された syntax を使用します。

カスタム ターゲットの入力として使用するデプロイ パラメータは、customTarget/ で始めることができます（例: customTarget/vertexAIModel）。この接頭辞を使用する場合は、環境変数としてデプロイ パラメータを参照するときに次の構文を使用します。

CLOUD_DEPLOY_customTarget_[VAR_NAME]

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

デプロイ　フックを使用してパラメータをデプロイする

デプロイフックでは、任意のデプロイ パラメータを環境変数として使用できます。

デプロイ検証を使用してパラメータをデプロイする

デプロイの検証では、任意のデプロイ パラメータを環境変数として使用できます。

リリースのすべてのパラメータを表示する

特定のリリースの設定パラメータを表示できます。これらの情報は、[リリースの詳細] ページとコマンド　ライン（gcloud deploy releases describe）の表に表示されます。

1. Cloud Deploy のメインページで、表示するリリースを含むデリバリー パイプラインをクリックします。

2. [リリースの詳細] ページで、[アーティファクト] タブを選択します。

このリリースに設定されたすべてのデプロイ パラメータは、1 つの列に変数名と値が表示され、もう 1 つの列には影響を受ける 1 つまたは複数のターゲットが表示されます。

次のステップ

• クイックスタート: デプロイ パラメータを使用するを試す。

• 並列デプロイを使用する際の詳細を確認する。