使用政策設定閘道資源

本頁說明如何設定負載平衡器。當您在 GKE 叢集中部署 Gateway 時，Google Kubernetes Engine (GKE) 會建立負載平衡器。

部署 Gateway 時，GatewayClass 設定會決定 GKE 建立的負載平衡器。這個代管負載平衡器已預先設定預設設定，您可以使用政策修改這些設定。

您可以將政策附加至閘道、服務或 ServiceImports，自訂閘道資源，以符合基礎架構或應用程式需求。套用或修改政策後，閘道控制器會處理政策，並自動重新設定基礎負載平衡器資源。這樣就不必刪除或重新建立閘道、路徑或服務資源。

事前準備

開始之前，請確認您已完成下列工作：

啟用 Google Kubernetes Engine API。

啟用 Google Kubernetes Engine API

如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update 指令，取得最新版本。較舊的 gcloud CLI 版本可能不支援執行本文件中的指令。
注意：如果是現有的 gcloud CLI 安裝項目，請務必設定 compute/region property。如果您主要使用區域叢集，請改為設定 compute/zone。設定預設位置後，即可避免 gcloud CLI 發生下列錯誤：One of [--zone, --region] must be supplied: Please specify location。如果叢集位置與您設定的預設位置不同，您可能需要在特定指令中指定位置。

請確認您有現有的 Autopilot 或 Standard 叢集。如要建立新叢集，請參閱「建立 Autopilot 叢集」。

GKE Gateway 控制器需求

閘道 API 僅支援虛擬私有雲原生叢集。
如果您使用區域或跨區域 GatewayClass，必須啟用僅限 Proxy 的子網路。
叢集必須啟用 HttpLoadBalancing 外掛程式。
如果您使用 Istio，請務必將 Istio 升級至下列其中一個版本：
- 1.15.2 以上版本
- 1.14.5 以上版本
- 1.13.9 以上版本。
如果您使用共用虛擬私有雲，則須在主專案中，將 Compute Network User 角色指派給服務專案的 GKE 服務帳戶。

限制

除了 GKE Gateway 控制器的限制，下列限制也適用於套用至 Gateway 資源的政策：

GCPGatewayPolicy 資源只能附加至 gateway.networking.k8s.io Gateway。
GCPGatewayPolicy 資源必須與目標 Gateway 位於相同命名空間。
使用單一叢集 Gateway 時，GCPBackendPolicy 和 HealthCheckPolicy 資源必須參照 Service 資源。
使用多叢集閘道時，GCPBackendPolicy 和 HealthCheckPolicy 資源必須參照 ServiceImport 資源。
服務一次只能附加一個 GCPBackendPolicy。如果建立的兩項 GCPBackendPolicy 政策指定了相同的 Service 或 ServiceImport，系統會優先採用較舊的政策，並無法附加第二項政策。
GKE Gateway 不支援階層式政策。
和 GCPBackendPolicy 資源必須與目標 Service 或 ServiceImport 資源位於相同命名空間。HealthCheckPolicy
GCPBackendPolicy 和 HealthCheckPolicy 資源的結構只能參照一個後端服務。
GCPBackendPolicy 不支援工作階段相依性的 HEADER_FIELD 或 HTTP_COOKIE 選項。如要使用 HEADER_FIELD 或 HTTP_COOKIE 工作階段相依性，請使用 GCPTrafficDistributionPolicy 資源。
使用不同範圍的閘道 (例如全域外部和區域內部) 時，如果需要不同的 GCPBackendPolicy 設定，就無法使用相同的後端 Service。舉例來說，全域 GCPBackendPolicy 無法套用至區域範圍的閘道，反之亦然。為確保範圍專屬政策正確無誤，請為每個 Gateway 範圍建立不同的 Service。
如果您在 GCPTrafficDistributionPolicy 和 GCPBackendPolicy 上設定工作階段親和性，且兩者都以相同的 Kubernetes 服務為目標，則 GCPTrafficDistributionPolicy 的設定會優先採用。
使用 GCPTrafficDistributionPolicy 設定的工作階段親和性僅適用於單一叢集閘道。
GCPTrafficDistributionPolicy 工作階段相依性與 InferencePool 資源不相容，因為這些資源使用專屬的區域負載平衡演算法。
GCPTrafficDistributionPolicy 不支援為傳統版應用程式負載平衡器設定工作階段親和性或地區負載平衡政策。

為區域內部閘道設定全域存取權

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

如要透過內部閘道啟用全域存取權，請將政策附加至閘道資源。

下列 GCPGatewayPolicy 資訊清單會啟用區域內部閘道，以供全域存取：

apiVersion: networking.gke.io/v1
kind: GCPGatewayPolicy
metadata:
  name: my-gateway-policy
  namespace: default
spec:
  default:
    # Enable global access for the regional internal Application Load Balancer.
    allowGlobalAccess: true
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: my-gateway

設定多叢集閘道的區域

本節說明 GKE 叢集 (執行 1.30.3-gke.1225000 以上版本) 提供的功能。

如果車隊的叢集遍布多個區域，您可能需要在不同區域部署區域閘道，以因應各種用途，例如跨區域備援、低延遲和資料主權。在多叢集閘道設定叢集中，您可以指定要部署區域閘道的區域。如果未指定地區，預設地區為設定叢集的地區。

如要為多叢集閘道設定區域，請使用 GCPGatewayPolicy 中的 region 欄位。在下列範例中，閘道是在 us-central1 區域中設定：

apiVersion: networking.gke.io/v1
kind: GCPGatewayPolicy
metadata:
  name: my-gateway-policy
  namespace: default
spec:
  default:
    region: us-central1
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: my-regional-gateway

設定 SSL 政策，確保用戶端到負載平衡器的流量安全

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

如要保護用戶端到負載平衡器的流量，請在 GCPGatewayPolicy 中新增政策名稱，藉此設定 SSL 政策。根據預設，閘道不會定義及附加任何 SSL 政策。

請務必建立 SSL 政策，再於 GCPGatewayPolicy 中參照該政策。

下列 GCPGatewayPolicy 資訊清單指定名為 gke-gateway-ssl-policy 的安全性政策：

apiVersion: networking.gke.io/v1
kind: GCPGatewayPolicy
metadata:
  name: my-gateway-policy
  namespace: team1
spec:
  default:
    sslPolicy: gke-gateway-ssl-policy
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: my-gateway

設定健康狀態檢查

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

根據預設，對於使用 HTTP 或 kubernetes.io/h2c 應用程式通訊協定的後端服務，HealthCheck 為 HTTP 類型。如果是 HTTPS 通訊協定，預設的健康狀態檢查為 HTTPS 類型。如果是 HTTP2 通訊協定，預設的健康狀態檢查為 HTTP2 類型。

您可以使用 HealthCheckPolicy 控制負載平衡器健康狀態檢查設定。每種健康狀態檢查 (http、https、grpc、http2 和 tcp) 都有可定義的參數。 Google Cloud會為每個 GKE 服務的每個後端服務建立專屬的健康狀態檢查。

如果健康狀態檢查路徑不是標準的「/」，您可能需要為負載平衡器設定自訂 HealthCheckPolicy，負載平衡器才能正常運作。如果路徑需要特殊標頭，或您需要調整健康狀態檢查參數，也必須進行這項設定。舉例來說，如果預設要求路徑為「/」，但您的服務無法透過該要求路徑存取，而是使用「/health」回報健康狀態，則您必須在 HealthCheckPolicy 中相應地設定 requestPath。

下列 HealthCheckPolicy 資訊清單顯示設定健康狀態檢查政策時的所有可用欄位：

服務

# Health check configuration for the load balancer. For more information
# about these fields, see https://cloud.google.com/compute/docs/reference/rest/v1/healthChecks.
apiVersion: networking.gke.io/v1
kind: HealthCheckPolicy
metadata:
  name: lb-healthcheck
  namespace: lb-service-namespace
spec:
  default:
    checkIntervalSec: INTERVAL  # The default value is 15 seconds.
    timeoutSec: TIMEOUT
    healthyThreshold: HEALTHY_THRESHOLD
    unhealthyThreshold: UNHEALTHY_THRESHOLD
    logConfig:
      enabled: true
    config:
      type: PROTOCOL
      httpHealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
      httpsHealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
      grpcHealthCheck:
        grpcServiceName: GRPC_SERVICE_NAME
        portSpecification: PORT_SPECIFICATION
        port: PORT
      http2HealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
      tcpHealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        portName: PORT_NAME
        request: REQUEST
        response: RESPONSE
        proxyHeader: PROXY_HEADER
  # Attach to a Service in the cluster.
  targetRef:
    group: ""
    kind: Service
    name: lb-service

多叢集服務

apiVersion: networking.gke.io/v1
kind: HealthCheckPolicy
metadata:
  name: lb-healthcheck
  namespace: lb-service-namespace
spec:
  # The default and config fields control the health check configuration for the
  # load balancer. For more information about these fields, see
  # https://cloud.google.com/compute/docs/reference/rest/v1/healthChecks.
  default:
    checkIntervalSec: INTERVAL
    timeoutSec: TIMEOUT
    healthyThreshold: HEALTHY_THRESHOLD
    unhealthyThreshold: UNHEALTHY_THRESHOLD
    logConfig:
      enabled: ENABLED
    config:
      type: PROTOCOL
      httpHealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
      httpsHealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
      grpcHealthCheck:
        grpcServiceName: GRPC_SERVICE_NAME
        portSpecification: PORT_SPECIFICATION
        port: PORT
      http2HealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
      tcpHealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        portName: PORT_NAME
        request: REQUEST
        response: RESPONSE
        proxyHeader: PROXY_HEADER
  # Attach to a multi-cluster Service by referencing the ServiceImport.
  targetRef:
    group: net.gke.io
    kind: ServiceImport
    name: lb-service

更改下列內容：

INTERVAL：指定每個健康狀態檢查探測器的檢查間隔 (以秒為單位)。這是指從某個探測系統開始檢查，到下一次檢查開始之間的時間。如果省略這個參數，且未指定 HealthCheckPolicy，預設值為 15 秒；如果指定 HealthCheckPolicy 但沒有 checkIntervalSec 值，預設值則為 5 秒。 Google Cloud 詳情請參閱「多個探測器和頻率」。
TIMEOUT：指定Google Cloud 等待探測回應的時間長度。TIMEOUT 的值必須小於或等於 INTERVAL。單位為秒。每次探測都必須在探測逾時前傳送 HTTP 200 (OK) 回應碼。
HEALTHY_THRESHOLD 和 UNHEALTHY_THRESHOLD：指定至少一個探測器必須連續成功或失敗多少次連線嘗試，才能將健康狀態從良好變更為不良，或從不良變更為良好。如果省略其中一個參數， Google Cloud 預設為 2。
PROTOCOL：指定探測系統用於健康狀態檢查的通訊協定。詳情請參閱「HTTP、HTTPS 和 HTTP/2 的成功標準」、「gRPC 的成功標準」和「TCP 的成功標準」。此為必要參數。
ENABLED：指定是否啟用或停用記錄功能。
PORT_SPECIFICATION：指定健康狀態檢查是否使用固定通訊埠 (USE_FIXED_PORT)、具名通訊埠 (USE_NAMED_PORT) 或服務通訊埠 (USE_SERVING_PORT)。如未指定，健康狀態檢查會遵循 port 欄位中指定的行為。如未指定 port，這個欄位會預設為 USE_SERVING_PORT。
PORT：HealthCheckPolicy 僅支援使用通訊埠編號指定負載平衡器健康狀態檢查通訊埠。如果省略這個參數，預設值為 80。 Google Cloud 由於負載平衡器會直接將探測訊號傳送至 Pod 的 IP 位址，因此即使 containerPort 是由服務的 targetPort 參照，您也應選取與服務 Pod 的 containerPort 相符的通訊埠。您不限於服務的 targetPort 所參照的 containerPorts。
HOST：健康狀態檢查要求中的主機標頭值。這個值會使用 RFC 1123 的主機名稱定義，但不得使用數字 IP 位址。如未指定或留空，這個值預設為健康檢查的 IP 位址。
REQUEST：指定在建立 TCP 連線後要傳送的應用程式資料。如未指定，預設值為空白。如果要求和回應都為空白，則已建立的連線本身即表示健康狀態。要求資料只能採用 ASCII 格式。
REQUEST_PATH：指定健康狀態檢查要求的 request-path。如未指定或留空，則預設為 /。
RESPONSE：指定要比對回應資料開頭的位元組。如果未指定或留空，GKE 會將任何回應解讀為狀態良好。回應資料只能是 ASCII。
PROXY_HEADER：指定 Proxy 標頭類型。您可以使用 NONE 或 PROXY_V1。預設為 NONE。
GRPC_SERVICE_NAME：gRPC 服務的選用名稱。如要指定所有服務，請省略這個欄位。

如要進一步瞭解 HealthCheckPolicy 欄位，請參閱healthChecks 參考資料。

設定 Cloud Armor 後端安全性政策，保護後端服務

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

將安全性政策名稱新增至 GCPBackendPolicy，即可設定 Cloud Armor 後端安全性政策，保護後端服務。根據預設，閘道不會定義及附加任何 Cloud Armor 後端安全性政策。

請務必建立 Cloud Armor 後端安全性政策，再於 GCPBackendPolicy 中參照該政策。如果您要啟用區域閘道，則必須建立區域 Cloud Armor 後端安全性政策。

下列 GCPBackendPolicy 資訊清單指定名為 example-security-policy 的後端安全性政策：

服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # Apply a Cloud Armor security policy.
    securityPolicy: example-security-policy
  # Attach to a Service in the cluster.
  targetRef:
    group: ""
    kind: Service
    name: lb-service

多叢集服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # Apply a Cloud Armor security policy.
    securityPolicy: example-security-policy
  # Attach to a multi-cluster Service by referencing the ServiceImport.
  targetRef:
    group: net.gke.io
    kind: ServiceImport
    name: lb-service

設定 IAP

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

Identity-Aware Proxy (IAP) 會對與 HTTPRoute 相關聯的後端服務強制執行存取控管政策。強制執行這項設定後，只有經過驗證的使用者或應用程式，且已指派正確的 Identity and Access Management (IAM) 角色，才能存取這些後端服務。

根據預設，後端服務不會套用 IAP，您必須在 GCPBackendPolicy 中明確設定 IAP。

如要透過 Gateway 設定 IAP，請按照下列步驟操作：

為 GKE 啟用 IAP 請勿設定後端 (設定 BackendConfig)，因為 BackendConfig 只在 Ingress 部署作業中有效。
為 IAP 建立密鑰：
1. 前往 Google Cloud 控制台的「憑證」頁面：
  
  前往「憑證」
2. 按一下用戶端名稱，然後下載 OAuth 用戶端檔案。
3. 從 OAuth 用戶端檔案中，將 OAuth 密碼複製到剪貼簿。
4. 建立名為 iap-secret.txt 的檔案。
5. 使用下列指令，將 OAuth 密鑰貼到 iap-secret.txt 檔案中：
```
echo -n CLIENT_SECRET > iap-secret.txt
kubectl create secret generic SECRET_NAME --from-file=key=iap-secret.txt
```

如要指定參照 Secret 的 IAP 政策：

建立下列 GCPBackendPolicy 資訊清單，並分別取代 SECRET_NAME 和 CLIENT_ID。將資訊清單儲存為 backend-policy.yaml：

服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: backend-policy
spec:
  default:
    # IAP OAuth2 settings. For more information about these fields,
    # see https://cloud.google.com/iap/docs/reference/rest/v1/IapSettings#oauth2.
    iap:
      enabled: true
      oauth2ClientSecret:
        name: SECRET_NAME
      clientID: CLIENT_ID
  # Attach to a Service in the cluster.
  targetRef:
    group: ""
    kind: Service
    name: lb-service

多叢集服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: backend-policy
spec:
  default:
    # IAP OAuth2 settings. For more information about these fields,
    # see https://cloud.google.com/iap/docs/reference/rest/v1/IapSettings#oauth2.
    iap:
      enabled: true
      oauth2ClientSecret:
        name: SECRET_NAME
      clientID: CLIENT_ID
  # Attach to a multi-cluster Service by referencing the ServiceImport.
  targetRef:
    group: net.gke.io
    kind: ServiceImport
    name: lb-service

套用 backend-policy.yaml 資訊清單：
```
kubectl apply -f backend-policy.yaml
```

驗證設定：

確認建立 GCPBackendPolicy 後，系統是否已套用政策 (使用 IAP)：
```
kubectl get gcpbackendpolicy
```
輸出結果會與下列內容相似：
```
NAME             AGE
backend-policy   45m
```

如要取得更多詳細資料，請使用 describe 指令：

kubectl describe gcpbackendpolicy

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

Name:         backend-policy
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         GCPBackendPolicy
Metadata:
  Creation Timestamp:  2023-05-27T06:45:32Z
  Generation:          2
  Resource Version:    19780077
  UID:                 f4f60a3b-4bb2-4e12-8748-d3b310d9c8e5
Spec:
  Default:
    Iap:
      Client ID:  441323991697-luotsrnpboij65ebfr13hlcpm5a4heke.apps.googleusercontent.com
      Enabled:    true
      oauth2ClientSecret:
        Name:  my-iap-secret
  Target Ref:
    Group:
    Kind:   Service
    Name:   lb-service
Status:
  Conditions:
    Last Transition Time:  2023-05-27T06:48:25Z
    Message:
    Reason:                Attached
    Status:                True
    Type:                  Attached
Events:
  Type     Reason  Age                 From                   Message
  ----     ------  ----                ----                   -------
  Normal   ADD     46m                 sc-gateway-controller  default/backend-policy
  Normal   SYNC    44s (x15 over 43m)  sc-gateway-controller  Application of GCPBackendPolicy "default/backend-policy" was a success

設定後端服務逾時

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

下列 GCPBackendPolicy 資訊清單指定 40 秒的後端服務逾時期間。「timeoutSec」欄位預設為 30 秒。

服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # Backend service timeout, in seconds, for the load balancer. The default
    # value is 30.
    timeoutSec: 40
  # Attach to a Service in the cluster.
  targetRef:
    group: ""
    kind: Service
    name: lb-service

多叢集服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    timeoutSec: 40
  # Attach to a multi-cluster Service by referencing the ServiceImport.
  targetRef:
    group: net.gke.io
    kind: ServiceImport
    name: lb-service

使用 `GCPBackendPolicy` 設定後端選取項目

您可以在 GCPBackendPolicy 中使用 CUSTOM_METRICS 平衡模式，設定特定自訂指標，藉此影響負載平衡器的後端服務分配流量的方式。這個平衡模式可根據您定義的自訂指標 (由應用程式後端回報) 進行負載平衡。

詳情請參閱「使用自訂指標負載平衡管理流量」。

backends[] 欄位中的 customMetrics[] 陣列包含下列欄位：

name：指定自訂指標的使用者定義名稱。
maxUtilization：為這項指標設定目標或最高用量。有效範圍為 [0, 100]。
dryRun：布林欄位。如果為 true，指標資料會回報給 Cloud Monitoring，但不會影響負載平衡決策。

範例

以下範例顯示 GCPBackendPolicy 資訊清單，可設定後端選取和端點層級路由的自訂指標。

將下列資訊清單儲存為 my-backend-policy.yaml：

kind: GCPBackendPolicy
apiVersion: networking.gke.io/v1
metadata:
  name: my-backend-policy
  namespace: team-awesome
spec:
  # Attach to the super-service Service.
  targetRef:
    kind: Service
    name: super-service
  default:
    backends:
    # Configuration for all locations.
    - location: "*"
      # Use the rate balancing mode for the load balancer.
      balancingMode: RATE
      # Maximum number of requests per second for each endpoint.
      maxRatePerEndpoint: 9000
    # Configuration for us-central1-a
    - location: us-central1-a
      # maxRatePerEndpoint: 9000 inherited from the * configuration.
      # Use the custom metrics balancing mode for the load balancer.
      balancingMode: CUSTOM_METRICS
      # Configure the custom metrics for the load balancer to use.
      customMetrics:
      - name: gpu-load
        maxUtilization: 100 # value ranges from 0 to 100 and maps to the floating pointrange [0.0, 1.0]
        dryRun: false

將資訊清單套用至叢集：

kubectl apply -f my-backend-policy.yaml

負載平衡器會根據RATE平衡模式和自訂gpu-load指標分配流量。

使用 GCPTrafficDistributionPolicy 設定端點層級的路由

Google Kubernetes Engine (GKE) Gateway 中的 GCPTrafficDistributionPolicy API 提供進階流量管理功能，可精確控管流量分配至應用程式 Pod 的方式。這個統一的 GKE 原生資源可簡化負載平衡演算法和工作階段親和性設定的管理作業。

GCPTrafficDistributionPolicy 可讓您設定：

負載平衡演算法：指定流量在後端端點之間的分配方式。
- WEIGHTED_ROUND_ROBIN：選取這個演算法後，負載平衡器會使用自訂指標計算權重，並根據這些回報的指標分配流量。GCPTrafficDistributionPolicy 設定中的 customMetrics[] 陣列包含下列欄位：
  - name：指定自訂指標的使用者定義名稱。
  - dryRun：當 true 時，指標資料會回報給 Cloud Monitoring，但不會影響負載平衡。
  注意： 在 GCPTrafficDistributionPolicy 中定義的自訂指標僅適用於 WEIGHTED_ROUND_ROBIN localityLbPolicy，不會從 GCPBackendPolicy 中的 backends[].customMetrics[] 繼承。
RING_HASH：這項演算法有助於提升對快取效能敏感的服務。這項功能會使用一致性雜湊，在新增或移除後端 Pod 時，盡量減少要求重新對應，確保擴充事件期間的穩定性。設定 minimumHashRingSize 可提供更精細的負載分配。
工作階段相依性：確保來自相同用戶端的要求一律會轉送至相同後端 Pod。這對有狀態工作負載至關重要，例如電子商務購物車或遊戲工作階段。GKE Gateway 支援應用程式負載平衡器執行個體提供的所有工作階段相依性類型，包括 HEADER_FIELD 和 HTTP_COOKIE。 Google Cloud

詳情請參閱「使用自訂指標負載平衡管理流量」。

範例

以下範例顯示 GCPTrafficDistributionPolicy 資訊清單，其中同時使用 WEIGHTED_ROUND_ROBIN 負載平衡演算法和自訂指標，設定端點層級的路由。

將下列範例資訊清單儲存為 GCPTrafficDistributionPolicy.yaml：

apiVersion: networking.gke.io/v1
kind: GCPTrafficDistributionPolicy
metadata:
  name: echoserver-v2
  namespace: team1
spec:
  targetRefs:
  # Attach to the echoserver-v2 Service in the cluster.
  - kind: Service
    group: ""
    name: echoserver-v2
  default:
    # Use custom metrics to distribute traffic across endpoints.
    localityLbAlgorithm: WEIGHTED_ROUND_ROBIN
    # Configure metrics from an ORCA load report to use for traffic
    # distribution.
    customMetrics:
    - name: orca.named_metrics.bescm11
      dryRun: false
    - name: orca.named_metrics.bescm12
      dryRun: true

將資訊清單套用至叢集：

kubectl apply -f GCPTrafficDistributionPolicy.yaml

負載平衡器會根據 WEIGHTED_ROUND_ROBIN 演算法和提供的自訂指標，將流量分配至端點。

設定雜湊環大小

如果服務極需減少快取失誤，請使用 RING_HASH 演算法。調整 minimumHashRingSize 可讓負載在後端之間更精細地分配。負載平衡器會自動管理環狀拓撲大小，但如果提供較高的最小值，有助於確保要求在較大的後端集中更平均地分配。

apiVersion: networking.gke.io/v1
kind: GCPTrafficDistributionPolicy
metadata:
  name: ring-hash-policy
  namespace: default
spec:
  default:
    localityLbAlgorithm: RING_HASH
    # Defaults to 1024. Larger ring sizes result in more granular
    # load distributions. Supported range is 1 to 2048.
    minimumHashRingSize: 1024
  targetRefs:
  -   group: ""
    kind: Service
    name: my-cache-heavy-service

設定工作階段相依性

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

您可以根據下列條件設定工作階段相依性：

用戶端 IP 位址
產生的 Cookie

為 Service 設定工作階段親和性時，Gateway 的 localityLbPolicy 設定會設為 MAGLEV。

從 GCPBackendPolicy 移除工作階段相依性設定後，Gateway 會將 localityLbPolicy 設定還原為預設值 ROUND_ROBIN。

下列 GCPBackendPolicy 資訊清單會根據用戶端 IP 位址指定工作階段相依性：

服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # On a best-effort basis, send requests from a specific client IP address
    # to the same backend. This field also sets the load balancer locality
    # policy to MAGLEV. For more information, see
    # https://cloud.google.com/load-balancing/docs/backend-service#lb-locality-policy
    sessionAffinity:
      type: CLIENT_IP
  targetRef:
    group: ""
    kind: Service
    name: lb-service

多叢集服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # On a best-effort basis, send requests from a specific client IP address
    # to the same backend. This field also sets the load balancer locality
    # policy to MAGLEV. For more information, see
    # https://cloud.google.com/load-balancing/docs/backend-service#lb-locality-policy
    sessionAffinity:
      type: CLIENT_IP
  targetRef:
    group: net.gke.io
    kind: ServiceImport
    name: lb-service

下列 GCPBackendPolicy 資訊清單會根據產生的 Cookie 指定工作階段相依性，並將 Cookie 的 TTL 設為 50 秒：

服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # Include an HTTP cookie in the Set-Cookie header of the response.
    # This field also sets the load balancer locality policy to MAGLEV. For more
    # information, see
    # https://cloud.google.com/load-balancing/docs/l7-internal#generated_cookie_affinity.
    sessionAffinity:
      type: GENERATED_COOKIE
      cookieTtlSec: 50  # The cookie expires in 50 seconds.
  targetRef:
    group: ""
    kind: Service
    name: lb-service

多叢集服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # Include an HTTP cookie in the Set-Cookie header of the response.
    # This field also sets the load balancer locality policy to MAGLEV. For more
    # information, see
    # https://cloud.google.com/load-balancing/docs/l7-internal#generated_cookie_affinity.
    sessionAffinity:
      type: GENERATED_COOKIE
      cookieTtlSec: 50  # The cookie expires in 50 seconds.
  targetRef:
    group: net.gke.io
    kind: ServiceImport
    name: lb-service

您可以在 sessionAffinity.type 欄位中使用下列值：

CLIENT_IP
GENERATED_COOKIE

使用 `GCPTrafficDistributionPolicy` 擴大工作階段相依性

GKE Gateway 支援使用 GCPTrafficDistributionPolicy 資源擴充工作階段相依性類型。這樣就能更精細地控管流量，例如根據自訂 HTTP 標頭或負載平衡器產生的 Cookie 進行路由。

下表說明使用 GCPTrafficDistributionPolicy 時支援的親和類型：

相依性類型	說明
`HEADER_FIELD`	根據特定 HTTP 標頭的相依性。必須將 `localityLbAlgorithm` 設為 `MAGLEV` 或 `RING_HASH`。
`HTTP_COOKIE`	以 HTTP Cookie 為基礎的相依性。回應第一個要求時，負載平衡器會產生 Cookie，並在 `Set-Cookie` 回應標頭中提供。在後續要求中，用戶端會傳回負載平衡器提供的 Cookie，負載平衡器則會使用該 Cookie，將要求一致地轉送至相同 Pod。您必須設定 `cookie.name`，並可視需要設定 `cookie.path` 和 `cookie.ttl`。必須將 `localityLbAlgorithm` 設為 `MAGLEV` 或 `RING_HASH`。
`GENERATED_COOKIE`	負載平衡器會產生 Cookie 來追蹤工作階段。全域外部應用程式負載平衡器的 Cookie 名稱為 `GCLB`，區域性內部應用程式負載平衡器和區域性外部應用程式負載平衡器的 Cookie 名稱為 `GCILB`，Cookie 路徑則為 `/`。您可以選擇設定`cookie.ttl`，最多可設定兩週；`cookie.name` 和 `cookie.path` 無法針對這類廣告設定。必須將 `localityLbAlgorithm` 設為 `MAGLEV` 或 `RING_HASH`。
`CLIENT_IP`	根據用戶端 IP 位址的親和性。必須將 `localityLbAlgorithm` 設為 `MAGLEV` 或 `RING_HASH`。

擴充工作階段相依性範例

GCPTrafficDistributionPolicy 支援多種工作階段相依性類型，每種類型都有獨特的設定需求。

設定 HTTP Cookie 型工作階段相依性

如果是購物車或遊戲伺服器等有狀態應用程式，請將要求路由至保存使用者工作階段資料的特定 Pod。這項設定使用 HTTP_COOKIE 相依性，根據負載平衡器產生的特定 Cookie 設定工作階段相依性，並在 Set-Cookie 標頭中傳回給用戶端。

將下列資訊清單儲存為 policy.yaml：

apiVersion: networking.gke.io/v1
kind: GCPTrafficDistributionPolicy
metadata:
  name: http-cookie-affinity-policy
  namespace: default
spec:
  default:
    sessionAffinity:
      type: HTTP_COOKIE
      cookie:
        name: "my-app-session-id"
        ttl: "1h"
        path: "/"
    # HTTP_COOKIE affinity requires localityLbAlgorithm to be MAGLEV or RING_HASH.
    localityLbAlgorithm: MAGLEV
  targetRefs:
  -   group: ""
    kind: Service
    name: my-stateful-service

將政策套用至叢集：
```
kubectl apply -f policy.yaml
```

Cookie 型工作階段相依性的零存留時間行為：

所有以 Cookie 為基礎的工作階段相依性 (例如 GENERATED_COOKIE 和 HTTP_COOKIE 相依性) 都具有 ttl 屬性。

如果存留時間為零秒，表示負載平衡器不會將 Expires 屬性指派給 Cookie。在這種情況下，用戶端會將 Cookie 視為工作階段 Cookie。工作階段的定義會因用戶端而異：

部分用戶端 (例如網路瀏覽器) 會在整個瀏覽工作階段保留 Cookie。這表示在應用程式關閉前，Cookie 會在多個要求中持續存在。
其他用戶端會將工作階段視為單一 HTTP 要求，並在之後立即捨棄 Cookie。

設定標頭型工作階段相依性

根據特定 HTTP 標頭傳送流量，適用於 A/B 測試或不適合使用 Cookie 的專業用戶端路由等情境。如要使用 NONE 以外的工作階段相依性類型，必須將 localityLbAlgorithm 設為 MAGLEV 或 RING_HASH。與預設 ROUND_ROBIN 不同，這些演算法支援以 HTTP 標頭等自訂欄位為準的一致性雜湊。

將下列資訊清單儲存為 policy.yaml：

apiVersion: networking.gke.io/v1
kind: GCPTrafficDistributionPolicy
metadata:
  name: header-affinity-policy
  namespace: default
spec:
  default:
    sessionAffinity:
      type: HEADER_FIELD
      httpHeaderName: "X-User-Group-ID"
    localityLbAlgorithm: MAGLEV
  targetRefs:
  -   group: ""
    kind: Service
    name: SERVICE_NAME

將政策套用至叢集：
```
kubectl apply -f policy.yaml
```

驗證政策

為確保 GCPTrafficDistributionPolicy 設定正確且有效，請在套用後驗證其狀態。

如要查看政策狀態，請說明政策：
```
kubectl describe gcptrafficdistributionpolicy POLICY_NAME
```
將 POLICY_NAME 替換為政策名稱。
在輸出內容中，尋找 Conditions 區段。如果狀態為 True，且原因為 Attached，表示設定有效且已套用。

設定連線排除逾時

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

您可以使用 GCPBackendPolicy 設定連線排除逾時。連線排除逾時是指等待連線排除的時間 (以秒計算)。逾時時間長度可介於 0 至 3,600 秒之間。預設值為 0，這也會停用連線排除功能。

下列 GCPBackendPolicy 資訊清單指定連線排除逾時為 60 秒：

服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    connectionDraining:
      drainingTimeoutSec: 60
  targetRef:
    group: ""
    kind: Service
    name: lb-service

多叢集服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    connectionDraining:
      drainingTimeoutSec: 60
  targetRef:
    group: net.gke.io
    kind: ServiceImport
    name: lb-service

在指定的逾時時間長度內，GKE 會等待傳送至已移除後端的現有要求完成。負載平衡器不會將新的要求傳送至已移除的後端。逾時時間長度屆滿之後，GKE 就會關閉所有剩餘的後端連線。

HTTP 存取記錄

本節說明 GKE 叢集 (須執行 1.24 以上版本) 提供的功能。

根據預設：

閘道控制器會將用戶端的所有 HTTP 要求記錄至 Cloud Logging。
取樣率為 1,000,000，表示系統會記錄所有要求。
系統不會記錄選填欄位。

您可以使用 GCPBackendPolicy，透過三種方式在 Gateway 上停用存取記錄：

你可以將「GCPBackendPolicy」部分留空logging
您可以將 logging.enabled 設為 false
您可以將 logging.enabled 設為 true，並將 logging.sampleRate 設為 0

您也可以設定存取記錄取樣率和選用欄位清單，例如「tls.cipher」或「orca_load_report」。

如要啟用選填欄位的記錄功能，請按照下列步驟操作：

將 logging.OptionalMode 設為 CUSTOM。
在 logging.optionalFields 中提供要記錄的選填欄位清單。如需支援的欄位清單，請參閱「記錄和監控」。

您可以透過下列兩種方式停用選填欄位的記錄功能：

你可以移除 logging.optionalFields 中的所有項目。
您可以將 logging.OptionalMode 設為 EXCLUDE_ALL_OPTIONAL。

下列 GCPBackendPolicy 資訊清單會修改存取記錄的預設取樣率，並將其設為 HTTP 要求的 50%。資訊清單也會針對特定 Service 資源啟用兩個選填欄位的記錄功能：

服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # Access logging configuration for the load balancer.
    logging:
      enabled: true
      # Log 50% of the requests. The value must be an integer between 0 and
      # 1000000. To get the proportion of requests to log, GKE
      # divides this value by 1000000.
      sampleRate: 500000
      # Log specific optional fields.
      optionalMode: CUSTOM
      optionalFields:
      - tls.cipher
      - orca_load_report.cpu_utilization
  targetRef:
    group: ""
    kind: Service
    name: lb-service

多叢集服務

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    # Access logging configuration for the load balancer.
    logging:
      enabled: true
      # Log 50% of the requests. The value must be an integer between 0 and
      # 1000000. To get the proportion of requests to log, GKE
      # divides this value by 1000000.
      sampleRate: 500000
      # Log specific optional fields.
      optionalMode: CUSTOM
      optionalFields:
      - tls.cipher
      - orca_load_report.cpu_utilization
  targetRef:
    group: net.gke.io
    kind: ServiceImport
    name: lb-service

這個資訊清單包含下列欄位：

enable: true：明確啟用存取記錄。記錄會顯示在「Logging」(記錄) 中。
sampleRate: 500000：指定要記錄 50% 的封包。你可以使用介於 0 到 1,000,000 之間的值。GKE 會將這個值除以 1, 000,000，轉換為介於 [0,1] 範圍內的浮點值。只有在 enable 設為 true 時，這個欄位才適用。sampleRate 是選填欄位，但如果設定了這個欄位，則必須一併設定 enable: true。如果 enable 設為 true，但未提供 sampleRate，GKE 會將 enable 設為 false。
optionalMode: CUSTOM：指定記錄項目中應包含一組 optionalFields。
optionalFields: tls.cipher, orca_load_report.cpu_utilization：指定記錄項目應包含 TLS 交握使用的密碼名稱，以及服務的 CPU 使用率 (如有)。

為單一叢集 Gateway 設定以流量為準的自動調度資源功能

確認 GKE 叢集執行的是 1.31.1-gke.2008000 以上版本。

如要在單一叢集 Gateway 中啟用以流量為準的自動調度資源和以容量為準的負載平衡，可以設定 Service 容量。服務容量是指服務可接收的流量容量，超過這個容量後，系統就會自動調度 Pod，或將流量溢流到其他可用叢集。

如要設定服務容量，請建立服務和相關聯的GCPBackendPolicy。GCPBackendPolicy 資訊清單使用 maxRatePerEndpoint 欄位，定義服務中每個 Pod 的每秒要求數 (RPS) 上限值。下列 GCPBackendPolicy 資訊清單定義的 RPS 上限為 10：

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: store
spec:
  default:
    maxRatePerEndpoint: 10
  targetRef:
    group: ""
    kind: Service
    name: store

如要進一步瞭解以流量為準的自動調度資源功能，請參閱「根據負載平衡器流量自動調度資源」一文。

疑難排解

本節提供相關指引，說明如何排解使用政策設定 Gateway 資源時的常見問題。

`GCPTrafficDistributionPolicy`未生效

症狀：流量未根據政策中定義的工作階段相依性或區域設定分配。

原因：如果政策未正確繫結至服務，或 Gateway 控制器嘗試將設定同步至負載平衡器時發生驗證錯誤，通常就會發生這種情況。

解決方法：

確認政策狀態：檢查政策是否已接受並附加至你的服務：
```
kubectl describe gcptrafficdistributionpolicy POLICY_NAME
```
將 POLICY_NAME 替換為政策名稱。

在輸出內容中，尋找 Conditions 區段。如果狀態為 True，且原因為 Attached，表示設定有效且已套用。如果狀態為 False，請檢查 Reason 和 Message 欄位是否有驗證錯誤 (例如所選親和類型不支援的演算法)。
確認閘道設定同步：確認管理流量的閘道已成功將這些設定與雲端基礎架構同步。

在 Status 部分中，確認 Programmed 條件的 Status 為 True。如果是 False，表示 Gateway 控制器發生錯誤，可能與 GCPTrafficDistributionPolicy 有關。

如要查看即時詳細資料，請檢查「Programmed」條件旁的「Reason」和「Message」欄位。如要查看更詳細的錯誤訊息或同步失敗記錄，請查看輸出內容底部的 Events。

流量分配期間會忽略工作階段相依性

症狀：

即使已設定工作階段親和性，要求也不會持續轉送至相同的後端 Pod。

原因：

加權流量分配的優先順序高於工作階段相依性。如果 HTTPRoute 為多個後端定義權重，負載平衡器會先根據權重選取後端，再套用親和性邏輯。

解決方法：

如果需要工作階段黏性，請避免在相同 HTTPRoute 規則中使用加權流量分配。

找不到 Cloud Armor 安全性政策

症狀：

在區域閘道上啟用 Cloud Armor 時，可能會出現下列錯誤訊息：

Invalid value for field 'resource': '{
"securityPolicy":"projects/123456789/regions/us-central1/securityPolicies/<policy_name>"}'.
The given security policy does not exist.

原因：

這則錯誤訊息表示您 Google Cloud 專案中沒有指定的區域性 Cloud Armor 安全性政策。

解決方法：

在專案中建立區域 Cloud Armor 安全性政策，並在 GCPBackendPolicy 中參照這項政策。

後續步驟

瞭解如何部署閘道。
進一步瞭解 Gateway 控制器。
瞭解如何從資源參照閘道。
查看 Policy Types API 參考資料。
查看 API 型別定義。

使用政策設定閘道資源 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

GKE Gateway 控制器需求

限制

為區域內部閘道設定全域存取權

設定多叢集閘道的區域

設定 SSL 政策，確保用戶端到負載平衡器的流量安全

設定健康狀態檢查

服務

多叢集服務

設定 Cloud Armor 後端安全性政策，保護後端服務

服務

多叢集服務

設定 IAP

服務

多叢集服務

設定後端服務逾時

服務

多叢集服務

使用 GCPBackendPolicy 設定後端選取項目

使用 GCPTrafficDistributionPolicy 設定端點層級的路由

設定雜湊環大小

設定工作階段相依性

服務

多叢集服務

服務

多叢集服務

使用 GCPTrafficDistributionPolicy 擴大工作階段相依性

擴充工作階段相依性範例

設定 HTTP Cookie 型工作階段相依性

設定標頭型工作階段相依性

驗證政策

設定連線排除逾時

服務

多叢集服務

HTTP 存取記錄

服務

多叢集服務

為單一叢集 Gateway 設定以流量為準的自動調度資源功能

疑難排解

GCPTrafficDistributionPolicy未生效

流量分配期間會忽略工作階段相依性

找不到 Cloud Armor 安全性政策

後續步驟

使用政策設定閘道資源

使用 `GCPBackendPolicy` 設定後端選取項目

使用 `GCPTrafficDistributionPolicy` 擴大工作階段相依性

`GCPTrafficDistributionPolicy`未生效