將參數傳遞至部署作業

使用 Cloud Deploy 時，您可以傳遞發布作業的參數，這些值會提供給資訊清單，然後再將資訊清單套用至各自的目標。這項替換作業會在資訊清單rendered後執行，是 Cloud Deploy 轉譯作業的最後一個步驟。系統會將值提供給 skaffold.yaml 檔案中所有含有對應預留位置的資訊清單。

您只需要在資訊清單中加入預留位置，並在 Cloud Deploy 交付管道或目標設定中，或是在建立版本時，設定這些預留位置的值即可。

本文將說明如何達成這個目標。

為何要使用部署參數？

這項功能通常用於在平行部署中，為不同目標套用不同的資訊清單值。不過，如果資訊清單中需要轉譯後鍵/值組合替換，您可以使用部署參數。

運作方式

下列步驟說明設定部署參數和提供值的一般程序：

1. 如這裡所述，設定部署參數化。

   包含下列項目：

   • 在資訊清單中加入預留位置，包括每個預留位置的預設值。

   • 為這些預留位置新增值。

     您可以透過三種方式進行這項操作，詳情請參閱這篇文章。

2. 建立版本時，系統會rendered資訊清單。

   如果您從範本資訊清單開始，系統現在會套用範本變數的值。如果從原始資訊清單開始，則不會有任何變更。這項算繪作業由 Skaffold 執行。

   不過，您可以在資訊清單中加入其他變數，這些變數的值不會在算繪時套用。這些是本文所述的部署參數。

   建立發布版本時，所有部署參數都會編譯成字典，用於在套用資訊清單前替換值。

   注意： 如果為特定部署參數 (鍵) 指派多個值，發布就會失敗。

3. 完成算繪後，Cloud Deploy 會替換部署參數的值。

   這些是您在第一個步驟中設定的值。

   算繪程序已將值套用至資訊清單範本、取代部分值，並新增 Cloud Deploy 專屬標籤。但這些部署參數的值會在算繪後替換。如要瞭解資訊清單範本和部署參數之間的差異，請參閱這篇文章。

4. 資訊清單會套用至目標執行階段，以部署應用程式。

   包括在算繪時替換的值，以及任何部署參數的值

傳遞值的不同方式

您可以透過下列三種方式提供參數和參數值：

• 在推送管道定義中

  您可以在傳送管道進度的階段定義中提供參數及其值。參數會傳遞至該階段代表的目標。如果該階段參照多重目標，系統會將這裡設定的值用於所有子目標。

  這個方法可為指定管道中的所有發行內容，以及所有受影響的目標，取代特定值。為階段定義的參數會識別標籤，而該階段的對應目標必須有相符的標籤。

• 在目標定義中

  您可以在目標本身的定義中設定參數及其值。這個方法可讓您為所有發行內容替換該目標的值。

• 在指令列中建立版本時

  使用 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_ 為保留字元，不得用於鍵名。

• 您無法將兩個同名鍵套用至相同目標。

• 值可以空白，但最多只能有 512 個字元。

• 部署參數預留位置無法用於 Helm 設定值，但必須依慣例傳遞。

設定部署參數

本節說明如何設定部署參數值，這些值會套用至 Kubernetes 資訊清單、Cloud Run 服務或 Helm 範本。

除了設定這些鍵/值組合，您還需要在資訊清單中加入預留位置，詳情請參閱本節。

在資訊清單中新增預留位置

在 Kubernetes 資訊清單 (適用於 GKE) 或服務 YAML (適用於 Cloud Run) 中，為您要在算繪後替換的任何值新增預留位置。

語法

如果發行版本未使用 Helm 算繪器搭配 Skaffold，請使用下列語法設定預留位置：

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

在這行中...

• PROPERTY:

  Kubernetes 資訊清單或 Cloud Run 服務 YAML 中的設定屬性。

• DEFAULT_VALUE

  如果指令列、管道或目標設定中未提供這個屬性的值，系統就會使用這個值。預設值為必要值，但可以是空字串 ("")。

• # from-param:

  使用註解字元設定 Cloud Deploy deploy-parameters 指令，並告知 Cloud Deploy 後方有 deploy-parameters 預留位置。from-param:

• ${VAR_NAME}

  這是要替換的預留位置。這必須與在發布管道或目標設定中提供的鍵/值組合的鍵相符，或與發布版本建立時的鍵相符。

您也可以在單行中使用多個參數，並將參數做為較長字串的一部分，例如：

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 正在安裝 Helm 圖表，該圖表會採用 webserver.port 的設定參數，指定網路伺服器啟動時使用的通訊埠，而您想從部署參數動態設定這個值，就必須建立名為 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`.

在管道階段中新增參數

您可以在發布管道的階段中新增鍵/值組合。 這適用於平行部署，可區分子目標。

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 是管道階段的設定，目標為多部署目標，在本例中，該目標有兩個子目標：

   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"
   

   在這個推送 pipeline 設定中，deployParameters 節包含兩個 values，每個節都有下列項目：

   • 變數名稱，與您在資訊清單中設定的變數名稱相同

   • 該變數的值

   • 一或多個標籤 (選用)，用於比對目標專屬標籤

     如果您未在 matchTargetLabels 節中指定標籤，該值會用於階段中的所有目標。

3. 如果您加入 matchTargetLabels，也必須在目標上加入標籤，以便進行比對。這樣一來，您就能判斷要將哪個值指派給哪個子目標。

   目標必須與 values 節中設定的所有標籤相符。

   如果省略 matchTargetLabels，您在管道上設定的 values 會套用至所有子項目標。但如果為相同參數設定多個值，發行內容就會失敗。

每個資訊清單完成算繪後，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
      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 是兩個目標的設定。每個目標都包含設定值的 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 會採用以半形逗號分隔的鍵/值組合清單，其中鍵是您新增至資訊清單的預留位置。

   指令如下所示：

   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 就會提供值。

使用自訂目標部署參數

您可以在自訂目標中使用任何部署參數做為環境變數。如要這麼做，請使用自訂目標指定的語法。

做為自訂目標輸入內容的部署參數可以 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. 在「發布詳細資料」頁面中，選取「構件」分頁標籤。

表格會顯示為這個版本設定的所有部署參數，其中一個資料欄會列出變數名稱和值，另一個資料欄則會列出受影響的目標。

後續步驟

• 請嘗試快速入門導覽課程：使用部署參數。

• 進一步瞭解如何使用平行部署。