使用服務擴充功能自訂 GKE 閘道流量


本頁說明 Google Kubernetes Engine (GKE) 如何使用服務擴充功能,將自訂邏輯新增至 Cloud Load Balancing。

本頁面適用於 GKE 身分和帳戶管理員,以及需要使用服務擴充功能設定自訂流量管理邏輯的開發人員。

閱讀本頁面之前,請先熟悉下列概念:

總覽

GKE 會使用服務擴充功能,將自訂邏輯新增至 Cloud Load Balancing。擴充功能會附加至 Gateway,並參照 ServiceGoogleAPIServiceNameGoogleAPIServiceName僅支援 GCPTrafficExtensions

您可以修改要求和回應的 HTTP 標頭和酬載,或控管流量轉送,而不影響後端服務選取或安全性政策。您可以透過 Service Extensions 執行進階流量拆分、自訂驗證或要求記錄等工作。

GKE Gateway 控制器支援下列服務擴充功能:

  • GCPRoutingExtension:這項擴充功能會在 Cloud Load Balancing 中加入自訂邏輯,以控管流量轉送。區域外部應用程式負載平衡器和區域內部應用程式負載平衡器都支援這項功能。

    `GCPRoutingExtension` 資源會附加至閘道,並參照服務。擴充功能會控管流量路徑。
    圖: GCPRoutingExtension 如何與閘道搭配運作
  • GCPTrafficExtension:這項擴充功能會將自訂邏輯插入 Cloud Load Balancing。擴充功能服務可藉此變更要求和回應的標頭和酬載。GCPTrafficExtension 不會影響後端服務選取項目或後端服務安全政策。

    `GCPTrafficExtension` 資源會附加至閘道,並參照服務或 `GoogleAPIServiceName`。擴充功能會變更要求和回應的標頭和酬載。
    圖: GCPTrafficExtension 如何與閘道搭配運作

Google Cloud Service Extension 與 GatewayClasses 的相容性

下表說明 Google Cloud 服務擴充功能與不同 GatewayClass 的相容性:

GatewayClass GCPRoutingExtension GCPTrafficExtension
gke-l7-rilb 支援 支援
gke-l7-regional-external-managed 支援 支援
gke-l7-global-external-managed 不支援 支援

事前準備

開始之前,請確認你已完成下列工作:

  • 啟用 Google Kubernetes Engine API。
  • 啟用 Google Kubernetes Engine API
  • 如要使用 Google Cloud CLI 執行這項工作,請安裝初始化 gcloud CLI。如果您先前已安裝 gcloud CLI,請執行 gcloud components update,取得最新版本。
  • 視需要啟用 Compute Engine API、Network Services API 和 Model Armor API。

    前往「啟用 API 存取權」,然後按照操作說明進行。

  • 如要進一步瞭解 Google Cloud 服務擴充功能的定價,請參閱「定價」一文。

  • 請參閱 服務擴充功能存取權控管,瞭解必要角色和權限。

  • 請詳閱 服務擴充功能配額,瞭解相關配額和限制。

  • 如要使用一般運算語言 (CEL) 比對器,請參閱 CEL 比對器語言參考資料,瞭解支援的屬性和運算子。

  • 查看服務擴充功能的限制

GKE Gateway 控制器需求

規定與限制

下表列出在 GKE 中設定 Gateway 服務擴充功能時的相關限制:

類別 規定與限制
負載平衡器 GCPRoutingExtension 僅支援區域性外部應用程式負載平衡器和區域性內部應用程式負載平衡器 (gke-l7-regional-external-managedgke-l7-rilb 閘道類別),不支援 gke-l7-global-external-managed 閘道類別。
擴充功能鏈和規格
  • 每個GCPTrafficExtension最多可有 3 個ExtensionChainExtensions
  • 每個 GCPRoutingExtension 最多只能有 1 個 ExtensionChainExtension
  • GCPTrafficExtensionSpecGCPRoutingExtensionSpec 各自最多可有 5 個 ExtensionChains
時間和比對
  • 擴充功能中串流的每則訊息逾時時間必須介於 10 到 1,000 毫秒之間。這項一秒限制適用於路線和交通資訊擴充功能。
  • 每個 ExtensionChain 內的 MatchCondition 最多只能有 10 個 CELExpressions
  • 傳送至 GCE 的結果 MatchCondition 字串長度上限為 512 個字元。
  • CELExpression 中的 CELMatcher 字串長度上限為 512 個字元,且必須符合特定模式。系統不支援 CELExpression 中的 BackendRefs 欄位。
標題和中繼資料
  • Extension 中的 ForwardHeaders 清單最多可包含 50 個 HTTP 標頭名稱。
  • Extension 中的 Metadata 對應最多可有 16 項屬性。
  • Metadata 對映中的鍵長度必須介於 1 至 63 個字元之間。
  • Metadata 對應中的值長度必須介於 1 到 1,023 個字元之間。
事件
  • 如果是 GCPRoutingExtension,如果未設定 requestBodySendModesupportedEvents 清單只能包含 RequestHeaders 事件。
  • 如果是 GCPRoutingExtension,如果 requestBodySendMode 設為 FullDuplexStreamed,則 supportedEvents 清單只能包含 RequestHeadersRequestBodyRequestTrailers 事件。
GCPTrafficExtension
  • responseBodySendMode 欄位僅支援 GCPTrafficExtension
  • googleAPIServiceName 欄位僅支援 GCPTrafficExtension
googleAPIServiceNamebackendRef 在擴充功能中參照使用 backendRef 的服務時,必須符合下列條件:
  • 必須使用 HTTP2 做為 appProtocol
  • 必須與擴充功能和擴充功能參照的閘道位於相同命名空間。
  • 無法使用 IAP
  • 無法使用 Google Cloud Armor 安全性政策 (來自 GCPBackendPolicyConfigsecurityPolicy 欄位)。
  • 無法使用 Cloud CDN
  • 請為 Extension 準確設定 backendRefgoogleAPIServiceName
  • 如已設定 backendRef,則必須設定 authority
  • 如已設定 googleAPIServiceName,則必須設定 authority
  • 請僅使用 backendRef 設定擴充功能的 requestBodySendMode
  • 請僅使用 backendRef 設定擴充功能的 responseBodySendMode

設定 GKE 服務擴充功能

您可以設定 GKE 服務擴充功能,自訂流量路徑、修改要求或回應酬載,以及與外部服務整合。閘道預設沒有 Service Extension。

如要設定 GKE 服務擴充功能,請按照下列步驟操作:

  1. 部署閘道:如要設定 GKE 服務擴充功能,您必須先部署閘道,將外部流量導向叢集。可以是全域外部應用程式負載平衡器、區域外部應用程式負載平衡器,或區域內部應用程式負載平衡器閘道。

    如要進一步瞭解如何部署閘道,請參閱「部署閘道」。

  2. 部署後端呼叫服務: 建立 Kubernetes 服務,代表用於執行自訂邏輯的後端服務。負載平衡器會叫用這項服務。

  3. 設定 Service Extensions:根據負載平衡器類型和需求,設定適當的 Service Extensions。

    1. GCPRoutingExtension 區域閘道:使用這個擴充功能,為區域性外部應用程式負載平衡器和區域性內部應用程式負載平衡器,在區域內實作自訂路由邏輯。

    2. GCPTrafficExtension 適用於全域外部、區域外部和內部閘道:使用這個擴充功能,對全域外部應用程式負載平衡器、區域外部應用程式負載平衡器和區域內部應用程式負載平衡器執行流量操控,例如修改標頭或檢查酬載,適用於各種負載平衡器類型。

部署後端呼叫服務

呼叫服務會為 GKE 中的閘道服務擴充功能實作自訂邏輯。閘道會根據 GCPTrafficExtensionGCPRoutingExtension 設定,叫用這些後端應用程式來修改或轉送流量。

您可以部署呼叫服務,在閘道中新增自訂邏輯。這個獨立服務會處理自訂處理作業,例如操控標頭、轉換酬載或路由流量。

如要部署可做為 Gateway 呼叫的後端服務,請按照下列步驟操作:

  1. (選用) 建立 TLS 密鑰: 這個指令會建立 TLS 類型的 Kubernetes 密鑰,其中包含 TLS 憑證和私密金鑰。

    如要為回呼服務建立 TLS 密鑰,請替換下列項目:

    • SECRET_NAME:回呼服務的密鑰名稱
    • path-to-cert:憑證的檔案路徑
    • path-to-key:金鑰的檔案路徑
  2. 如要確認已新增密鑰,請執行下列指令:

    kubectl get secrets SECRET_NAME
    

    SECRET_NAME 替換為回呼服務的密鑰名稱。

    畫面會顯示如下的輸出內容:

    NAME            TYPE                DATA   AGE
    SECRET_NAME     kubernetes.io/tls   2      12s
    
  3. 定義 Deployment 和 Service 資源。

    您必須定義下列項目:

    • Deployment:管理含有自訂邏輯的應用程式 Pod,適用於服務擴充功能。
    • Service:將 Deployment 管理的應用程式 Pod 公告為網路服務。
    1. 建立範例資訊清單 extension-service-app.yaml,其中包含 Deployment 和 Service 定義:

      apiVersion: apps/v1
      kind: Deployment
      metadata:
      name: extension-service-app
      spec:
      selector:
          matchLabels:
            app: store
        replicas: 1
        template:
          metadata:
            labels:
              app: store
          spec:
            containers:
            - name: serviceextensions
              image: us-docker.pkg.dev/service-extensions-samples/callouts/python-example-basic:main
              ports:
              - containerPort: 8080
              - containerPort: 443
              volumeMounts:
              - name: certs
                mountPath: "/etc/certs/"
                readOnly: true
              env:
              - name: POD_NAME
                valueFrom:
                  fieldRef:
                    fieldPath: metadata.name
              - name: NAMESPACE
                valueFrom:
                  fieldRef:
                    fieldPath: metadata.namespace
              - name: TLS_SERVER_CERT
                value: "/etc/certs/path-to-cert"
              - name: TLS_SERVER_PRIVKEY
                value: "/etc/certs/path-to-key"
                resources:
                requests:
                  cpu: 10m
            volumes:
            - name: certs
              secret:
                secretName: SECRET_NAME
                optional: false
      ---
      apiVersion: v1
      kind: Service
      metadata:
        name: extension-service
      spec:
        ports:
        - port: 443
          targetPort: 443
          appProtocol: HTTP2
        selector:
          app: store
      
    2. 套用 extension-service-app.yaml 資訊清單:

      kubectl apply -f extension-service-app.yaml
      
  4. 驗證設定:

    1. 確認應用程式已部署:

      kubectl get pod --selector app=store
      

      應用程式開始執行後,輸出內容會類似如下:

      NAME                                     READY   STATUS    RESTARTS   AGE
      extension-service-app-85f466bc9b-b5mf4   1/1     Running   0          7s
      
    2. 確認服務已部署:

      kubectl get service extension-service
      

      輸出內容會與下列內容相似,顯示每個商店部署作業的服務:

      NAME                TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
      extension-service   ClusterIP   34.118.225.9   <none>        443/TCP   2m40s
      

設定服務擴充功能

您可以設定 GCPRoutingExtensionGCPTrafficExtension,自訂流量。

設定區域閘道的 GCPRoutingExtension

您可以使用 GCPRoutingExtension 重新導向流量。如要設定 GCPRoutingExtension,請更新 HTTPRoute,指定 service-extensions.com 主機的要求。

  1. 更新 HTTPRoute。修改 HTTPRoute,加入會觸發轉送擴充功能的網域名稱或路徑。

    1. 將下列範例資訊清單儲存為 store-route.yaml 檔案:

      kind: HTTPRoute
      apiVersion: gateway.networking.k8s.io/v1
      metadata:
        name: store
      spec:
        parentRefs:
        - kind: Gateway
          name:GATEWAY_NAME
        hostnames:
        - "store.example.com"
        - "service-extensions.example.com"
        rules:
        - backendRefs:
          - name: store-v1
            port: 8080
        - matches:
          - headers:
            - name: env
              value: canary
          backendRefs:
          - name: store-v2
            port: 8080
        - matches:
          - path:
              value: /de
          backendRefs:
          - name: store-german
            port: 8080
      

      GATEWAY_NAME 替換為閘道名稱。

    2. 套用 store-route.yaml 資訊清單:

      kubectl apply -f store-route.yaml
      
  2. 定義 GCPRoutingExtension

    1. GCPRoutingExtension 設定儲存至範例 gcp-routing-extension.yaml 檔案:

      kind: GCPRoutingExtension
      apiVersion: networking.gke.io/v1
      metadata:
        name: my-gateway-extension
        namespace: default
      spec:
        targetRefs:
        - group: "gateway.networking.k8s.io"
          kind: Gateway
          name: GATEWAY_NAME
        extensionChains:
        - name: chain1
          matchCondition:
            celExpressions:
            - celMatcher: request.path.contains("serviceextensions")
          extensions:
          - name: ext1
            authority: "myext.com"
            timeout: 1s
              backendRef:
                group: ""
              kind: Service
              name: extension-service
              port: 443
      

      GATEWAY_NAME 替換為您的閘道名稱。

    2. 將範例資訊清單套用至叢集:

      kubectl apply -f gcp-routing-extension.yaml
      
  3. 驗證 GCPRoutingExtension 的設定,以及與閘道的繫結。

    1. 檢查 GCPRoutingExtension 部署作業:

      kubectl describe gcproutingextension my-gateway-extension
      

      輸出結果會與下列內容相似:

      Name:         my-gateway-extension
      Namespace:    default
      Labels:       <none>
      Annotations:  <none>
      API Version:  networking.gke.io/v1
      Kind:         GCPRoutingExtension
      Metadata:
        Creation Timestamp:  2025-03-02T17:12:30Z
        Generation:        1
        Resource Version:  31283253
        UID:               ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
      Spec:
        Extension Chains:
          Extensions:
            Authority:    myext.com
            Backend Ref:
              Group:
              Kind: Service
              Name: extension-service
              Port: 443
            Name:       ext1
            Timeout:    1s
          Match Condition:
            Cel Expressions:
              Cel Matcher: request.path.contains("serviceextensions")
          Name:  chain1
        Target Refs:
          Group: gateway.networking.k8s.io
          Kind: Gateway
          Name: GATEWAY_NAME
      Events:  <none>
      

      輸出內容會顯示預設命名空間中名為 my-gateway-extensionGCPRoutingExtension 詳細資料。輸出內容會顯示 Spec 欄位,其中包含擴充功能行為的定義。

    2. 驗證 Gateway 繫結:

      1. 確認 GCPRoutingExtension 已繫結至閘道。這項作業可能需要幾分鐘:

        kubectl describe gateway GATEWAY_NAME
        

        輸出結果會與下列內容相似:

        Name:         GATEWAY_NAME
        Namespace:    default
        Labels:       none
        Annotations:  networking.gke.io/addresses: /projects/1234567890/regions/us-central1/addresses/test-hgbk-default-internal-http-5ypwen3x2gcr
                      networking.gke.io/backend-services:
                        /projects/1234567890/regions/us-central1/backendServices/test-hgbk-default-extension-service-443-rduk21fwhoj0, /projects/1234567890/re...
                      networking.gke.io/firewalls: /projects/1234567890/global/firewalls/test-hgbk-l7-default-us-central1
                      networking.gke.io/forwarding-rules: /projects/1234567890/regions/us-central1/forwardingRules/test-hgbk-default-internal-http-qn7dk9i9zm73
                      networking.gke.io/health-checks:
                        /projects/1234567890/regions/us-central1/healthChecks/test-hgbk-default-extension-service-443-rduk21fwhoj0, /projects/1234567890/regio...
                      networking.gke.io/last-reconcile-time: 2025-03-02T17:15:02Z
                      networking.gke.io/lb-route-extensions:
                        /projects/1234567890/locations/us-central1/lbRouteExtensions/test-hgbk-default-internal-http-lwh0op4qorb0
                      networking.gke.io/lb-traffic-extensions:
                      networking.gke.io/ssl-certificates:
                      networking.gke.io/target-http-proxies:
                        /projects/1234567890/regions/us-central1/targetHttpProxies/test-hgbk-default-internal-http-2jzr7e3xclhj
                      networking.gke.io/target-https-proxies:
                      networking.gke.io/url-maps: /projects/1234567890/regions/us-central1/urlMaps/test-hgbk-default-internal-http-2jzr7e3xclhj
        API Version:  gateway.networking.k8s.io/v1
        Kind:         Gateway
        Metadata:
          Creation Timestamp:  2025-03-02T16:37:50Z
          Finalizers:
          gateway.finalizer.networking.gke.io
          Generation:        1
          Resource Version:  31284863
          UID:               fd512611-bad2-438e-abfd-5619474fbf31
        ...
        

        輸出內容會顯示註解,GKE 會使用這些註解儲存 Gateway 與基礎Google Cloud 資源之間的連結。networking.gke.io/lb-route-extensions 註解會確認閘道與 GCPRoutingExtension 的繫結。

      2. 確認 GCPRoutingExtension 具有 Reconciled 狀態和 ReconciliationSucceeded 原因,即可檢查擴充功能的狀態。這項指令可能需要幾分鐘才能完成。

        kubectl describe gcproutingextension my-gateway-extension
        

        輸出結果會與下列內容相似:

        Name:         my-gateway-extension
        Namespace:    default
        Labels:       <none>
        Annotations:  <none>
        API Version:  networking.gke.io/v1
        Kind:         GCPRoutingExtension
        Metadata:
          Creation Timestamp:  2025-03-02T17:12:30Z
          Generation:          1
          Resource Version:    31284378
          UID:                 ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
        Spec:
          Extension Chains:
            Extensions:
              Authority:  myext.com
              Backend Ref:
                Group:
                Kind:   Service
                Name:   extension-service
                Port:   443
              Name:     ext1
              Timeout:  1s
            Match Condition:
              Cel Expressions:
                Cel Matcher:  request.path.contains("serviceextensions")
            Name:             chain1
          Target Refs:
            Group:  gateway.networking.k8s.io
            Kind:   Gateway
            Name:   GATEWAY_NAME
        Status:
          Ancestors:
            Ancestor Ref:
              Group:      gateway.networking.k8s.io
              Kind:       Gateway
              Name:       GATEWAY_NAME
              Namespace:  default
            Conditions:
              Last Transition Time:  2025-03-02T17:14:15Z
              Message:
              Reason:                Accepted
              Status:                True
              Type:                  Accepted
              Last Transition Time:  2025-03-02T17:14:15Z
              Message:
              Reason:                ReconciliationSucceeded
              Status:                True
              Type:                  Reconciled
            Controller Name:         networking.gke.io/gateway
        Events:
          Type    Reason  Age                From                   Message
          ----    ------  ----               ----                   -------
          Normal  ADD     2m31s              sc-gateway-controller  default/my-gateway-extension
        Normal  SYNC    51s (x2 over 98s)  sc-gateway-controller  Attachment of GCPRoutingExtension "default/my-gateway-extension" to AncestorRef {Group:       "gateway.networking.k8s.io",
        Kind:        "Gateway",
        Namespace:   "default",
        Name:        "GATEWAY_NAME",
        SectionName: nil,
        Port:        nil} was a success
          Normal  SYNC    23s           sc-gateway-controller  Reconciliation of GCPRoutingExtension "default/my-gateway-extension" to AncestorRef {Group:       "gateway.networking.k8s.io",
        Kind:        "Gateway",
        Namespace:   "default",
        Name:        "GATEWAY_NAME",
        SectionName: nil,
        Port:        nil} was a success
        

        Status.Conditions 欄位會顯示 Reconciled 條件,並包含 Status: TrueReason: ReconciliationSucceeded

        正確和原因:ReconciliationSucceeded。這項資訊確認擴充功能已成功套用。

  4. 將流量傳送至應用程式。

    在叢集中部署 Gateway、Route 和應用程式後,即可將流量傳遞至應用程式。

    1. 如要存取應用程式,請找出閘道的 IP 位址。

      在終端機中,使用下列指令:

      kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
      

      GATEWAY_NAME 替換為您的閘道名稱。

      這個指令會輸出閘道的 IP 位址。在後續指令中,將 GATEWAY_IP_ADDRESS 替換為輸出內容中的 IP 位址。

    2. 前往 store.example.com/serviceextensionsserviceextensions 版本商店服務,測試路徑更新:

      curl http://store.example.com/serviceextensions --resolve store.example.com:80:GATEWAY_IP_ADDRESS -v
      

      輸出結果會與下列內容相似:

      {
      "cluster_name": "gke1",
      "host_header": "service-extensions.com",
      "metadata": "store-v1",
      "pod_name": "store-v1-5d9554f847-cvxpd",
      "pod_name_emoji": "💇🏼‍♀️",
      "project_id": "gateway-demo",
      "timestamp": "2025-03-15T12:00:00",
      "zone": "us-central1-c"
      }
      

設定 GCPTrafficExtension

您可以使用 GCPTrafficExtension,在 Google Cloud 環境中運用進階流量管理功能。您可以在全域外部應用程式負載平衡器、區域外部應用程式負載平衡器和區域內部應用程式負載平衡器中,設定這項擴充功能。您可以使用 GCPTrafficExtension 實作自訂要求和回應邏輯、複雜的路由、轉換和安全政策。

  1. 更新 HTTPRoute。修改 HTTPRoute,加入會觸發流量擴充功能的主機名稱或路徑。

    1. 將下列範例資訊清單儲存為 store-route.yaml 檔案:

      kind: HTTPRoute
      apiVersion: gateway.networking.k8s.io/v1
      metadata:
        name: store
      spec:
        parentRefs:
        - kind: Gateway
          name: GATEWAY_NAME
        hostnames:
        - "store.example.com"
        - "service-extensions.example.com"
        rules:
        - backendRefs:
          - name: store-v1
            port: 8080
        - matches:
          - headers:
            - name: env
              value: canary
          backendRefs:
          - name: store-v2
            port: 8080
        - matches:
          - path:
              value: /de
          backendRefs:
          - name: store-german
            port: 8080
      

      GATEWAY_NAME 替換為閘道的名稱,例如 internal-httpexternal-httpglobal-external-http

    2. store-route.yaml 資訊清單套用至叢集:

      kubectl apply -f store-route.yaml
      
  2. 定義 GCPTrafficExtension

    1. GCPTrafficExtension 設定儲存至範例 gcp-traffic-extension.yaml 檔案:

      kind: GCPTrafficExtension
      apiVersion: networking.gke.io/v1
      metadata:
        name: my-traffic-extension
        namespace: default
      spec:
        targetRefs:
        - group: "gateway.networking.k8s.io"
          kind: Gateway
          name: GATEWAY_NAME
        extensionChains:
        - name: chain1
          matchCondition:
            celExpressions:
            - celMatcher: request.path.contains("serviceextensions")
          extensions:
          - name: ext1
            authority: "myext.com"
            timeout: 1s
            backendRef:
              group: ""
              kind: Service
              name: extension-service
              port: 443
      

      GATEWAY_NAME 替換為閘道名稱,例如 internal-httpexternal-httpglobal-external-http

    2. 將範例資訊清單套用至叢集:

      kubectl apply -f gcp-traffic-extension.yaml
      
  3. 驗證 GCPTrafficExtension 的設定,以及與閘道的繫結。

    1. 檢查 GCPTrafficExtension 部署作業:

      kubectl describe gcptrafficextension my-traffic-extension
      

      輸出結果會與下列內容相似:

      Name:         my-traffic-extension
      Namespace:    default
      Labels:       <none>
      Annotations:  <none>
      API Version:  networking.gke.io/v1
      Kind:         GCPTrafficExtension
      Metadata:
        Creation Timestamp:  2025-03-02T17:12:30Z
        Generation:        1
        Resource Version:  31283253
        UID:               ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
      Spec:
        Extension Chains:
          Extensions:
            Authority:    myext.com
            Backend Ref:
              Group:
              Kind: Service
              Name: extension-service
              Port: 443
            Name:       ext1
            Timeout:    1s
          Match Condition:
            Cel Expressions:
              Cel Matcher: request.path.contains("serviceextensions")
          Name:  chain1
        Target Refs:
          Group: gateway.networking.k8s.io
          Kind: Gateway
          Name: GATEWAY_NAME
      Events:  <none>
      

      輸出內容會顯示預設命名空間中名為 GCPTrafficExtensionmy-traffic-extension 詳細資料。其中顯示 Spec 欄位,包含擴充功能行為的定義。

    2. 驗證 Gateway 繫結:

      確認 GCPTrafficExtension 已繫結至閘道。這個指令可能需要幾分鐘才能完成:

      kubectl describe gateway GATEWAY_NAME
      

      輸出結果會與下列內容相似:

      Name:         GATEWAY_NAME
      Namespace:    default
      Labels:       <none>
      Annotations:  networking.gke.io/addresses: /projects/1234567890/regions/us-central1/addresses/test-hgbk-default-internal-http-5ypwen3x2gcr
                    networking.gke.io/backend-services:
                      /projects/1234567890/regions/us-central1/backendServices/test-hgbk-default-extension-service-443-rduk21fwhoj0, /projects/1234567890/re...
                    networking.gke.io/firewalls: /projects/1234567890/global/firewalls/test-hgbk-l7-default-us-central1
                    networking.gke.io/forwarding-rules: /projects/1234567890/regions/us-central1/forwardingRules/test-hgbk-default-internal-http-qn7dk9i9zm73
                    networking.gke.io/health-checks:
                      /projects/1234567890/regions/us-central1/healthChecks/test-hgbk-default-extension-service-443-rduk21fwhoj0, /projects/1234567890/regio...
                    networking.gke.io/last-reconcile-time: 2025-03-02T17:15:02Z
                    networking.gke.io/lb-traffic-extensions:
                      /projects/1234567890/locations/us-central1/lbTrafficExtensions/test-hgbk-default-internal-http-lwh0op4qorb0
                    networking.gke.io/ssl-certificates:
                    networking.gke.io/target-http-proxies:
                      /projects/1234567890/regions/us-central1/targetHttpProxies/test-hgbk-default-internal-http-2jzr7e3xclhj
                    networking.gke.io/target-https-proxies:
                    networking.gke.io/url-maps: /projects/1234567890/regions/us-central1/urlMaps/test-hgbk-default-internal-http-2jzr7e3xclhj
      API Version:  gateway.networking.k8s.io/v1
      Kind:         Gateway
      Metadata:
        Creation Timestamp:  2025-03-02T16:37:50Z
        Finalizers:
          gateway.finalizer.networking.gke.io
        Generation:        1
        Resource Version:  31284863
        UID:               fd512611-bad2-438e-abfd-5619474fbf31
      ...
      

      輸出內容會顯示註解,GKE 會使用這些註解儲存 Gateway 與基礎 Google Cloud 資源之間的連結。networking.gke.io/lb-traffic-extensions 註解會確認繫結。

    3. 檢查擴充功能狀態:

      確認 GCPTrafficExtension 的狀態為 Reconciled,且原因為 ReconciliationSucceeded。這個指令可能需要幾分鐘才能完成。

      kubectl describe gcptrafficextension my-traffic-extension
      

      輸出結果會與下列內容相似:

      Name:         my-traffic-extension
      Namespace:    default
      Labels:       <none>
      Annotations:  <none>
      API Version:  networking.gke.io/v1
      Kind:         GCPTrafficExtension
      Metadata:
        Creation Timestamp:  2025-03-02T17:12:30Z
        Generation:          1
        Resource Version:    31284378
        UID:                 ec8efaa0-d8e7-4e1b-9fd4-0ae0ef3c74d0
      Spec:
        Extension Chains:
          Extensions:
            Authority:  myext.com
            Backend Ref:
              Group:
              Kind:   Service
              Name:   extension-service
              Port:   443
            Name:     ext1
            Timeout:  1s
          Match Condition:
            Cel Expressions:
              Cel Matcher:  request.path.contains("serviceextensions")
          Name:             chain1
        Target Refs:
          Group:  gateway.networking.k8s.io
          Kind:   Gateway
          Name:   GATEWAY_NAME
      Status:
        Ancestors:
          Ancestor Ref:
            Group:      gateway.networking.k8s.io
            Kind:       Gateway
            Name:       GATEWAY_NAME
            Namespace:  default
          Conditions:
            Last Transition Time:  2025-03-02T17:14:15Z
            Message:
            Reason:                Accepted
            Status:                True
            Type:                  Accepted
            Last Transition Time:  2025-03-02T17:14:15Z
            Message:
            Reason:                ReconciliationSucceeded
            Status:                True
            Type:                  Reconciled
          Controller Name:         networking.gke.io/gateway
      Events:
        Type    Reason  Age                From                   Message
        ----    ------  ----               ----                   -------
        Normal  ADD     2m31s              sc-gateway-controller  default/my-traffic-extension
        Normal  SYNC    51s (x2 over 98s)  sc-gateway-controller  Attachment of GCPTrafficExtension "default/my-gateway-extension" to AncestorRef {Group:       "gateway.networking.k8s.io",
        Kind:        "Gateway",
        Namespace:   "default",
        Name:        "GATEWAY_NAME",
        SectionName: nil,
        Port:        nil} was a success
        Normal  SYNC    23s           sc-gateway-controller  Reconciliation of GCPTrafficExtension "default/my-traffic-extension" to AncestorRef {Group:       "gateway.networking.k8s.io",
        Kind:        "Gateway",
        Namespace:   "default",
        Name:        "GATEWAY_NAME",
        SectionName: nil,
        Port:        nil} was a success
      

      Status.Conditions 欄位會顯示 Reconciled 條件,其中包含 Status: TrueReason: ReconciliationSucceeded。這項資訊確認擴充功能已成功套用。

  4. 將流量傳送至應用程式。

    在叢集中部署 Gateway、Route 和應用程式後,即可將流量傳遞至應用程式。

    1. 如要存取應用程式,請找出閘道的 IP 位址。

      在終端機中,使用下列指令:

      kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
      

      GATEWAY_NAME 替換為您的閘道名稱。

      這個指令會輸出閘道的 IP 位址。在後續指令中,將 GATEWAY_IP_ADDRESS 替換為輸出內容中的 IP 位址。

    2. 前往 store.example.com/serviceextensionsserviceextensions 版本商店服務,測試路徑更新:

      curl http://store.example.com/serviceextensions --resolve store.example.com:80:GATEWAY_IP_ADDRESS -v
      

      輸出結果會與下列內容相似:

      {
      *   Request completely sent off
      < HTTP/1.1 200 OK
      < server: Werkzeug/2.3.7 Python/3.11.3
      < date: Sun, 02 Mar 2025 16:58:10 GMT
      < content-type: application/json
      < access-control-allow-origin: *
      < hello: service-extensions
      < via: 1.1 google
      < transfer-encoding: chunked
      }
      

排解閘道上的流量擴充功能問題

本節提供在閘道上設定流量擴充功能的疑難排解提示。

找不到閘道

下列錯誤表示 GCPTrafficExtensionGCPRoutingExtension 資源的 targetRefs 欄位中指定的 Gateway 資源不存在:

error: failed to create resource: GCPTrafficExtension.networking.gke.io "my-traffic-extension" is invalid: spec.gatewayRef: gateway "my-gateway" not found in namespace "default"

如要解決這個問題,請確認 GCPTrafficExtensionGCPRoutingExtension 資源的 targetRefs 欄位中指定的 Gateway 資源存在於指定命名空間。

找不到服務或服務埠

如果 GCPTrafficExtensionGCPRoutingExtension 資源的 backendRef 欄位中指定的 Service 或 Service 通訊埠不存在,就會發生下列錯誤:

error: failed to create resource: GCPTrafficExtension.networking.gke.io "my-traffic-extension" is invalid: spec.service: service "callout-service" not found in namespace "default"

如要解決這個問題,請確認 GCPTrafficExtensionGCPRoutingExtension 資源的 backendRef 欄位中指定的服務和服務通訊埠,存在於指定的命名空間。

NEG 中沒有網路端點

下列錯誤表示 NEG 中沒有與 GCPTrafficExtensionGCPRoutingExtension 資源的 backendRef 欄位中指定服務相關聯的網路端點:

error: failed to create resource: GCPTrafficExtension.networking.gke.io "my-traffic-extension" is invalid: spec.service: no network endpoints found for service "callout-service"

如要解決這個問題,請確認 GCPTrafficExtensionGCPRoutingExtension 資源的 backendRef 欄位中指定的服務具有網路端點。

傳送要求後未收到回覆或收到錯誤回覆

如果傳送要求後未收到回覆,或收到含有錯誤的回覆,可能表示叫用服務無法正常運作。

如要解決這個問題,請檢查外呼服務的記錄是否有任何錯誤。

JSON 酬載中的錯誤代碼 404

如果出現下列錯誤,表示系統找不到叫用服務,或該服務未回應要求:

{
  "error": {
    "code": 404,
    "message": "Requested entity was not found.",
    "status": "NOT_FOUND"
  }
}

如要解決這個問題,請確認呼叫服務正在執行、監聽的連接埠正確無誤,且服務已在 GCPTrafficExtensionGCPRoutingExtension 資源中正確設定。

JSON 酬載中的錯誤代碼 500

下列錯誤表示叫用服務發生內部伺服器錯誤:

{
  "error": {
    "code": 500,
    "message": "Internal server error.",
    "status": "INTERNAL"
  }
}

如要解決這個問題,請檢查呼叫服務的記錄,找出內部伺服器錯誤的原因。

後續步驟