使用 Gateway API 網路功能，將 Canary 部署至 GKE 和 GKE Enterprise

本文說明如何設定及使用 Canary 部署，透過 Cloud Deploy 和 Kubernetes Gateway API 服務網格，將應用程式部署至 GKE 或 GKE Enterprise。

初期測試部署是指逐步推出應用程式新版本，逐步增加傳送至新版本的流量百分比，同時監控應用程式的效能。這有助於及早發現潛在問題，並盡量減少對使用者的影響。

如何使用 Gateway API，為 GKE 和 GKE Enterprise 執行 Canary 部署作業

  1. 除了 Deployment 和 Service 參照，您還提供 HTTPRoute 資源，其中包含參照 Service 的 backendRefs 規則。

  2. Cloud Deploy 會建立新的 Deployment，名稱為原始 Deployment 名稱加上 -canary，以及新的 Service，名稱為原始 Service 名稱加上 -canary。

    系統也會複製 Secret、ConfigMap 和水平 Pod 自動調度器，並使用 -canary 重新命名。

  3. 在每個 Canary 階段，Cloud Deploy 會修改 HTTPRoute，根據該階段的百分比，更新原始 Deployment 的 Pod 與 Canary Deployment 的 Pod 之間的權重。

    變更傳播至 HTTPRoute 資源時可能會發生延遲，因此您可以在設定中加入 routeUpdateWaitTime 屬性，讓系統等待指定時間，確保變更傳播完成。

  4. 在 stable 階段，-canary Deployment 會縮減至零，而原始 Deployment 會更新為使用新版本的 Deployment。

    此外，HTTPRoute 現在已還原為您提供的原始狀態。

    在 stable 階段之前，Cloud Deploy 不會修改原始的 Deployment 或 Service。

使用 Cloud Deploy 時，您可以在單一或多個階段中，將 Canary 部署作業設定為 GKE 和 GKE Enterprise。

這裡的操作說明僅包含 Canary 設定專屬的內容。請參閱「將應用程式部署至 Google Kubernetes Engine 叢集」一文，瞭解如何設定及執行部署管道。

確認您具備必要權限

除了使用 Cloud Deploy 時需要的其他 Identity and Access Management 權限，您還需要下列權限，才能執行可能需要用於 Canary 部署作業的其他動作：

  • clouddeploy.rollouts.advance
  • clouddeploy.rollouts.ignoreJob
  • clouddeploy.rollouts.cancel
  • clouddeploy.rollouts.retryJob
  • clouddeploy.jobRuns.get
  • clouddeploy.jobRuns.list
  • clouddeploy.jobRuns.terminate

如要進一步瞭解哪些可用角色包含這些權限，請參閱「IAM 角色和權限」。

準備好「skaffold.yaml」

skaffold.yaml 檔案會定義 Kubernetes 資訊清單的算繪和部署方式。如要將 Canary 部署至 GKE/GKE Enterprise，請確認其正確指向資訊清單，並定義所有必要的建構構件。除了標準部署所需的設定外，skaffold.yaml 本身不需要任何特殊的 Canary 專用設定。您可能會使用 Skaffold 設定檔，管理自訂 Canary 階段的不同資訊清單變體。

準備 Kubernetes 資訊清單

Kubernetes 資訊清單必須包含 Deployment 資源和 Service 資源。Service 必須定義與 Deployment 所管理 Pod 標籤相符的 selector。Cloud Deploy 預設會尋找 app 標籤，但您可以在管道中設定這個標籤。

除了 Deployment 和 Service 之外，資訊清單還必須包含為流量分配設定的 HTTPRoute 資源，並參照 Service 和相關聯的閘道。

設定自動初期測試

使用 Kubernetes Gateway API (搭配 Istio 或任何支援的實作方式)，透過網格/閘道管理精確的百分比流量分配，並由 Cloud Deploy 協調。

  1. 設定 Gateway API 資源：請確認您的 Gateway 和基礎服務網格 (例如 叢集中已正確設定 Istio 或 Gateway 控制器。

  2. 在您建立版本時提供給 Cloud Deploy 的 Kubernetes 資訊清單中，加入下列項目：

    • 參照 Gateway 資源的 HTTPRoute

    • Deployment

    • 服務

  3. 設定推送管道和要進行初期測試部署的目標：

    • 目標的設定方式與任何目標相同。

    • 在特定目標的進展順序中，交付管道設定包含 gatewayServiceMesh 節，可參照 Kubernetes Gateway API HTTPRoute 設定，以及 Deployment 和 Service。

      strategy:
 canary:
   runtimeConfig:
     kubernetes:
       gatewayServiceMesh:
         httpRoute: "ROUTE"
         service: "SERVICE"
         deployment: "DEPLOYMENT"
         routeUpdateWaitTime: "WAIT_TIME"
         podSelectorLabel: "LABEL"
   canaryDeployment:
     percentages:
     - 50

      Where...

      • ROUTE 是 httpRoute 設定，用於定義所需的轉送行為。

      • SERVICE 是服務設定，Cloud Deploy 需要這項設定，才能將 Canary 部署作業部署至 GKE 和 GKE Enterprise。

      • DEPLOYMENT 是 Deployment 設定，Cloud Deploy 需要這項設定，才能將 Canary 部署作業部署至 GKE 和 GKE Enterprise。

      • WAIT_TIME 是 Cloud Deploy 等待 HTTPRoute 資源變更完成傳播的時間長度，可避免要求遭到捨棄。例如：routeUpdateWaitTime: 60s。

        如果您使用 Gateway API 執行 Canary，但沒有 Istio，且 Gateway API 連線至 Google Cloud 負載平衡器，當 Canary 執行個體縮減時，可能會遺失少量流量。如果發生這種情況，您可以設定這項設定。

      • LABEL 是 Pod 選擇器標籤。這必須與資訊清單中定義的 Kubernetes 服務和部署項目中的標籤選取器相符。這項設定為選填。預設值為 app。

設定自訂初期測試

您可以手動設定 Canary，不必完全依賴 Cloud Deploy 提供的自動化功能。透過自訂 Canary 設定，您可以在推送管道定義中指定下列項目：

  • 推出階段名稱

    在全自動 Canary 部署中，Cloud Deploy 會為您命名階段 (例如 canary-25、canary-75、stable)。不過，使用自訂 Canary 時，您可以為每個階段命名，只要該名稱在 Canary 階段的所有階段中不重複，且符合資源 ID 限制即可。但最後階段 (100%) 的名稱必須是 stable。

  • 各階段的百分比目標

    分別指定每個階段的百分比。

  • 階段要使用的 Skaffold 設定檔

    您可以為每個階段使用不同的 Skaffold 設定檔，也可以使用相同的設定檔，或任意組合。每個設定檔都可以使用不同的 Kubernetes 資訊清單。您也可以在特定階段使用多個設定檔。Cloud Deploy 會合併這些項目。

  • 階段是否有驗證工作

    請注意，啟用驗證後，您也需要設定 skaffold.yaml 以進行驗證。

  • 階段是否有部署前或部署後作業

    如要啟用部署前或部署後工作，請設定這些工作的 skaffold.yaml。

自訂 Canary 支援所有目標類型。

自訂初期測試設定元素

下列 YAML 顯示完全自訂 Canary 部署階段的設定：

strategy:
  canary:
    # Custom configuration for each canary phase
    customCanaryDeployment:
      phaseConfigs:
      - phaseId: "PHASE1_NAME"
        percentage: PERCENTAGE1
        profiles: [ "PROFILE_NAME" ]
        verify: true | false
        predeploy:
          actions: "PREDEPLOY_ACTION"
        postdeploy:
          actions: "POSTDEPLOY_ACTION"
      - …
      - phaseId: "stable"
        percentage: 100
        profiles: [ "LAST_PROFILE_NAME" ]
        verify: true|false
        predeploy:
          actions: "PREDEPLOY_ACTION"
        postdeploy:
          actions: "POSTDEPLOY_ACTION"

這個 YAML

  • PHASE1_NAME

    是階段的名稱。每個階段名稱都不得重複。

  • [ "PROFILE_NAME" ]

    這是要用於階段的設定檔名稱。您可以為每個階段使用相同的設定檔，也可以為每個階段使用不同的設定檔，或任意組合。此外，您也可以指定多個設定檔。Cloud Deploy 會使用您指定的所有設定檔，加上整體階段使用的設定檔或資訊清單。

  • stable

    最後一個階段必須命名為 stable。

  • PERCENTAGE1

    這是第一階段要部署的百分比。每個階段都必須有專屬的百分比值，且該值必須是整數百分比 (例如不得為 10.5)，階段也必須依遞增順序排列。

  • verify: true|false

    告知 Cloud Deploy 是否要為階段納入驗證工作。 請注意，如要讓每個階段都使用驗證，Skaffold 會使用相同的設定檔進行驗證，該設定檔是為該階段的算繪和部署作業指定。

  • PREDEPLOY_ACTION

    與您在 skaffold.yaml 中使用的 ACTION_NAME 相同，可定義要在部署前執行的自訂動作。

  • POSTDEPLOY_ACTION

    與您在 skaffold.yaml 中用來定義部署後要執行的自訂動作的 ACTION_NAME 相同。

最後階段的百分比必須為 100。系統會按照您在這個 customCanaryDeployment 節中設定的順序執行階段，但如果百分比值不是遞增順序，註冊發布管道的指令就會失敗並顯示錯誤。

請注意，Gateway API 自訂 Canary 版的設定不包含 runtimeConfig 節。如果加入 runtimeConfig，則會視為以自訂服務為基礎的 Canary 版本。

設定自訂自動初期測試

這項功能結合了自訂階段定義 (名稱、百分比、設定檔、驗證、掛鉤)，以及 Cloud Deploy 的 GKE 或 GKE Enterprise 自動流量管理功能。您定義階段，但 Cloud Deploy 會根據百分比和所選的 runtimeConfig，處理基礎資源操作。

如要設定這項功能，請在 strategy.canary 區塊中，同時加入 runtimeConfig 區段 (含 serviceNetworking) 和 customCanaryDeployment 區段 (定義 phaseConfigs)。Cloud Deploy 會使用指定的 Skaffold 設定檔進行算繪，但會根據 runtimeConfig 和階段百分比自動調整流量。

serialPipeline:
  stages:
  - targetId: gke-prod
    profiles: []
    strategy:
      canary:
        # Include runtimeConfig for automatic traffic management
        runtimeConfig:
          kubernetes:
            gatewayServiceMesh:
              httpRoute: "my-route"
              service: "my-app"
              deployment: "my-deployment"  
        # Include customCanaryDeployment for phase customization
        customCanaryDeployment:
          phaseConfigs:
          - phaseId: "warmup"
            percentage: 10
            profiles: ["profile-a"] # Profile used for rendering this phase
            verify: true
          - phaseId: "scaling"
            percentage: 50
            profiles: ["profile-b"] # Different profile for this phase
            verify: true
          - phaseId: "stable"
            percentage: 100
            profiles: ["profile-b"] # Can reuse profiles
            verify: true

將 HTTPRoute 部署至其他叢集

使用 Gateway API 服務網格設定 Canary 時，您可以指定要部署 HTTPRoute 的替代非目標叢集。

如要這麼做，請在 Canary 策略設定中使用 routeDestinations 節，找出 HTTPRoute 的目的地叢集，並使用布林值設定將 Service 傳播至相同的非目標叢集。您會在目標設定中建立 associatedEntities 節，以識別叢集。

  1. 在目標上設定 associatedEntities。

    每個實體都是叢集，Cloud Deploy 會在其中部署 HTTPRoute，以及 Kubernetes 服務 (選用)。在目標定義中加入 associatedEntities 節：

    associatedEntities:
  [KEY]:
    gkeClusters:
    - cluster: [PATH]
      dnsEndpoint: [true|false]
      internalIp: [true|false]
      proxyUrl:

    其中：

    • KEY 是這個關聯實體群組的任意名稱。您會使用這個名稱，從 Canary 設定中參照實體。routeDestinations

    • PATH 是資源路徑，用於識別要部署 HTTPRoute (和選用的 Service) 的 GKE 叢集。

    • dnsEndpoint 表示是否要使用叢集的 DNS 端點 (如果已設定多個端點)。預設值為 false。

    • internalIp 表示是否要使用叢集的內部 IP (私人 IP)，前提是已設定多個端點。預設值為 false。

    您可以納入任意數量的叢集，無論是否含有 internalIp。

  2. 在初期測試設定中設定 routeDestinations。

    每條路徑目的地都會參照 associatedEntities 節，並指出是否也要將服務部署至替代叢集。在 Canary 設定的 gatewayServiceMesh 節中加入以下內容：

    routeDestinations:
  destinationIds: ["KEY"]
  propagateService: [true|false]

    其中：

    • KEY 是您在 associatedEntities 的目標中設定的名稱。在 Canary 設定中，使用這個名稱參照 routeDestinations 中的實體。

      您也可以提供 @self 值，將 HTTPRoute 部署至目標叢集，以及相關聯的目的地。

    • propagateService 表示除了 HTTPRoute 之外，是否要將 Service 部署至相關聯的叢集。預設值為 false。

執行 GKE 或 GKE Enterprise Canary

  1. 註冊管道和目標：套用交付管道和 GKE 或 GKE Enterprise 目標設定檔。

    
gcloud deploy apply --file=delivery-pipeline.yaml --region=REGION
gcloud deploy apply --file=gke-targets.yaml --region=REGION

    推送管道包含所選執行階段的自動或自訂 Canary 設定。

  2. 建立版本：開始部署作業，並提供映像檔名稱。

    
gcloud deploy releases create RELEASE_NAME \
                                --delivery-pipeline=PIPELINE_NAME \
                                --region=REGION
  # e.g., --images=my-cloudrun-service=gcr.io/my-project/my-app:v1.1
  # Add --skaffold-file or --source if not using default Skaffold config discovery

    由 PIPELINE_NAME 識別的推送管道包含本文所述的自動或自訂 Canary 設定。

  3. 推進初期測試版本：

    gcloud CLI 

    gcloud deploy rollouts advance ROLLOUT_NAME \
                            --release=RELEASE_NAME \
                            --delivery-pipeline=PIPELINE_NAME \
                            --region=REGION

    其中：

    ROLLOUT_NAME 是目前要推進至下一階段的推出作業名稱。

    RELEASE_NAME 是指這個推出作業所屬的版本名稱。

    PIPELINE_NAME 是您用來管理這個版本部署作業的發布管道名稱。

    REGION 是建立版本的區域名稱，例如 us-central1。必填。

    如要進一步瞭解 gcloud deploy rollouts advance 指令，請參閱 Google Cloud SDK 參考資料。

    Google Cloud 控制台

    1. 開啟「推送管道」頁面。

    2. 在推送管道清單中，按一下您的管道。

      「推送 pipeline 詳細資料」頁面會以圖形呈現推送 pipeline 的進度。

    3. 在「推出」分頁的「發布管道詳細資料」下方，按一下推出作業的名稱。

      系統隨即會顯示該推出作業的詳細資料頁面。

      在 Google Cloud 控制台查看推出作業詳細資料

      請注意，在本範例中，發布作業有 canary-50 階段和 stable 階段。您的推出作業可能會有更多或不同的階段。

    4. 按一下「進展至下一個推出階段」。

      推出作業會推進至下一個階段。

略過的階段

如果您部署初期測試版本，但應用程式尚未部署至該執行階段，Cloud Deploy 會略過初期測試階段，並執行穩定階段。請參閱「首次略過階段」，瞭解發生這種情況的原因。

後續步驟