本頁面由 Cloud Translation API 翻譯而成。

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

自動駕駛標準

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

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

閱讀本頁面之前，請先熟悉下列概念：

總覽

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

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

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

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

圖： GCPRoutingExtension 如何與閘道搭配運作
GCPTrafficExtension：這項擴充功能會將自訂邏輯插入 Cloud Load Balancing。擴充功能服務可藉此變更要求和回應的標頭和酬載。GCPTrafficExtension 不會影響後端服務選取項目或後端服務安全政策。

圖： 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，取得最新版本。
注意：如果是現有的 gcloud CLI 安裝項目，請務必設定 compute/region 和 compute/zone 屬性。設定預設位置後，即可避免 gcloud CLI 發生下列錯誤： One of [--zone, --region] must be supplied: Please specify location.

視需要啟用 Compute Engine API、Network Services API 和 Model Armor API。

前往「啟用 API 存取權」，然後按照操作說明進行。
如要進一步瞭解 Google Cloud 服務擴充功能的定價，請參閱「定價」一文。
請參閱服務擴充功能存取權控管，瞭解必要角色和權限。
請詳閱服務擴充功能配額，瞭解相關配額和限制。
如要使用一般運算語言 (CEL) 比對器，請參閱 CEL 比對器語言參考資料，瞭解支援的屬性和運算子。

注意： 系統不支援 request.backend_service_name 和 request.backend_service_project_number 要求屬性。
查看服務擴充功能的限制。

GKE Gateway 控制器需求

叢集必須使用 GKE 1.33 以上版本。
叢集必須啟用 Gateway API。
您必須設定 Gateway 資源。
您必須設定 HTTPRoute 資源。

規定與限制

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

類別	規定與限制
負載平衡器	`GCPRoutingExtension` 僅支援區域性外部應用程式負載平衡器和區域性內部應用程式負載平衡器 (`gke-l7-regional-external-managed` 和 `gke-l7-rilb` 閘道類別)，不支援 `gke-l7-global-external-managed` 閘道類別。
擴充功能鏈和規格	每個`GCPTrafficExtension`最多可有 3 個`ExtensionChainExtensions`。每個 `GCPRoutingExtension` 最多只能有 1 個 `ExtensionChainExtension`。 `GCPTrafficExtensionSpec` 和 `GCPRoutingExtensionSpec` 各自最多可有 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`，如果未設定 `requestBodySendMode`，`supportedEvents` 清單只能包含 `RequestHeaders` 事件。如果是 `GCPRoutingExtension`，如果 `requestBodySendMode` 設為 `FullDuplexStreamed`，則 `supportedEvents` 清單只能包含 `RequestHeaders`、`RequestBody` 和 `RequestTrailers` 事件。
`GCPTrafficExtension`	`responseBodySendMode` 欄位僅支援 `GCPTrafficExtension`。 `googleAPIServiceName` 欄位僅支援 `GCPTrafficExtension`。
`googleAPIServiceName` 和 `backendRef`	在擴充功能中參照使用 `backendRef` 的服務時，必須符合下列條件：必須使用 HTTP2 做為 `appProtocol`。必須與擴充功能和擴充功能參照的閘道位於相同命名空間。無法使用 IAP。無法使用 Google Cloud Armor 安全性政策 (來自 `GCPBackendPolicyConfig` 的 `securityPolicy` 欄位)。無法使用 Cloud CDN。請為 `Extension` 準確設定 `backendRef` 或 `googleAPIServiceName`。如已設定 `backendRef`，則必須設定 `authority`。如已設定 `googleAPIServiceName`，則必須設定 `authority`。請僅使用 `backendRef` 設定擴充功能的 `requestBodySendMode`。請僅使用 `backendRef` 設定擴充功能的 `responseBodySendMode`。

設定 GKE 服務擴充功能

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

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

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

如要進一步瞭解如何部署閘道，請參閱「部署閘道」。
部署後端呼叫服務：建立 Kubernetes 服務，代表用於執行自訂邏輯的後端服務。負載平衡器會叫用這項服務。
設定 Service Extensions：根據負載平衡器類型和需求，設定適當的 Service Extensions。
1. GCPRoutingExtension 區域閘道：使用這個擴充功能，為區域性外部應用程式負載平衡器和區域性內部應用程式負載平衡器，在區域內實作自訂路由邏輯。
2. GCPTrafficExtension 適用於全域外部、區域外部和內部閘道：使用這個擴充功能，對全域外部應用程式負載平衡器、區域外部應用程式負載平衡器和區域內部應用程式負載平衡器執行流量操控，例如修改標頭或檢查酬載，適用於各種負載平衡器類型。

部署後端呼叫服務

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

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

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

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

如要為回呼服務建立 TLS 密鑰，請替換下列項目：
- SECRET_NAME：回呼服務的密鑰名稱
- path-to-cert：憑證的檔案路徑
- path-to-key：金鑰的檔案路徑
如要確認已新增密鑰，請執行下列指令：
```
kubectl get secrets SECRET_NAME
```
將 SECRET_NAME 替換為回呼服務的密鑰名稱。

畫面會顯示如下的輸出內容：
```
NAME            TYPE                DATA   AGE
SECRET_NAME     kubernetes.io/tls   2      12s
```

定義 Deployment 和 Service 資源。

您必須定義下列項目：

Deployment：管理含有自訂邏輯的應用程式 Pod，適用於服務擴充功能。
Service：將 Deployment 管理的應用程式 Pod 公告為網路服務。

建立範例資訊清單 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

套用 extension-service-app.yaml 資訊清單：

kubectl apply -f extension-service-app.yaml

驗證設定：

確認應用程式已部署：

kubectl get pod --selector app=store

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

NAME                                     READY   STATUS    RESTARTS   AGE
extension-service-app-85f466bc9b-b5mf4   1/1     Running   0          7s

確認服務已部署：

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

設定服務擴充功能

您可以設定 GCPRoutingExtension 或 GCPTrafficExtension，自訂流量。

設定區域閘道的 `GCPRoutingExtension`

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

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

將下列範例資訊清單儲存為 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 替換為閘道名稱。

套用 store-route.yaml 資訊清單：
```
kubectl apply -f store-route.yaml
```

定義 GCPRoutingExtension。

將 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 替換為您的閘道名稱。

將範例資訊清單套用至叢集：

kubectl apply -f gcp-routing-extension.yaml

驗證 GCPRoutingExtension 的設定，以及與閘道的繫結。

檢查 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-extension 的 GCPRoutingExtension 詳細資料。輸出內容會顯示 Spec 欄位，其中包含擴充功能行為的定義。

驗證 Gateway 繫結：

確認 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 的繫結。

確認 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: True 和 Reason: ReconciliationSucceeded。

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

將流量傳送至應用程式。

在叢集中部署 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/serviceextensions 的 serviceextensions 版本商店服務，測試路徑更新：
```
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 實作自訂要求和回應邏輯、複雜的路由、轉換和安全政策。

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

將下列範例資訊清單儲存為 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-http、external-http 或 global-external-http。

將 store-route.yaml 資訊清單套用至叢集：
```
kubectl apply -f store-route.yaml
```

定義 GCPTrafficExtension。

將 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-http、external-http 或 global-external-http。

將範例資訊清單套用至叢集：

kubectl apply -f gcp-traffic-extension.yaml

驗證 GCPTrafficExtension 的設定，以及與閘道的繫結。

檢查 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>

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

驗證 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 註解會確認繫結。

檢查擴充功能狀態：

確認 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: True 和 Reason: ReconciliationSucceeded。這項資訊確認擴充功能已成功套用。

將流量傳送至應用程式。

在叢集中部署 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/serviceextensions 的 serviceextensions 版本商店服務，測試路徑更新：
```
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
}
```

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

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

找不到閘道

下列錯誤表示 GCPTrafficExtension 或 GCPRoutingExtension 資源的 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"

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

找不到服務或服務埠

如果 GCPTrafficExtension 或 GCPRoutingExtension 資源的 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"

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

NEG 中沒有網路端點

下列錯誤表示 NEG 中沒有與 GCPTrafficExtension 或 GCPRoutingExtension 資源的 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"

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

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

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

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

JSON 酬載中的錯誤代碼 404

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

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

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

JSON 酬載中的錯誤代碼 500

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

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

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

使用服務擴充功能自訂 GKE 閘道流量 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

事前準備

GKE Gateway 控制器需求

規定與限制

設定 GKE 服務擴充功能

部署後端呼叫服務

設定服務擴充功能

設定區域閘道的 GCPRoutingExtension

設定 GCPTrafficExtension

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

找不到閘道

找不到服務或服務埠

NEG 中沒有網路端點

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

JSON 酬載中的錯誤代碼 404

JSON 酬載中的錯誤代碼 500

後續步驟

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

設定區域閘道的 `GCPRoutingExtension`

設定 `GCPTrafficExtension`