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

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

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

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

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

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

仕組み

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

1. デプロイのパラメータ化は、こちらで説明するように構成します。

   サポート対象は次のとおりです。

   • マニフェストにプレースホルダを追加します。

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

     これを行う方法は 3 つあります。こちらをご覧ください。

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

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

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

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

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

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

   これらは、最初のステップで構成した値です。

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

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

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

値を渡すさまざまな方法

パラメータとそれらのパラメータの値は、次の 3 つの方法で指定できます。

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

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

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

• ターゲットの定義内で

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

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

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

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

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

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

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

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

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

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

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

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

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

制限事項

• パラメータのタイプごとに最大 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 文字の制限があります。

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

このセクションでは、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 固有の構文

Skaffold で Helm レンダラを使用している場合は、Helm テンプレートで次の構文を使用してプレースホルダを追加します。

[PROPERTY]:  {{ .Values.VAR_NAME }} 

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

デリバリー パイプライン進行のステージに 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
   

   この例では、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 はレンダリングされたマニフェストに値を指定します。

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

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

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

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

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

次のステップ

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

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