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

Cloud Deploy を使用すると、リリースのパラメータを渡し、それらの値をマニフェストに提供してから、マニフェストをそれぞれのターゲットに適用できます。この置換は、マニフェストがrendered後に行われます。これは、Cloud Deploy レンダリング オペレーションの最後のステップです。値は、対応するプレースホルダを含む 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 コマンドはエラーで失敗します。

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

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

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

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

制限事項

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

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

  • キー名は、最大 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 ペアのキーと一致する必要があります。

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 が含まれ、それぞれに以下の対象が設定されています。

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

    • 変数の値

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

      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

    この例では、commit 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 は デプロイ パラメータ名の斜線の後の部分です。たとえば、customTarget/vertexAIModel という名前のデプロイ パラメータを定義した場合は、CLOUD_DEPLOY_customTarget_vertexAIModel として参照します。

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

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

デプロイ検証でデプロイ パラメータをデプロイする

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

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

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

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

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

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

Google Cloud コンソールに表示されるデプロイ パラメータと値

次のステップ