Gateway API v1.2：WebSockets、超時、重試等

Kubernetes SIG Network 很高興地宣佈 Gateway API v1.2 正式釋出！該版本的 API 於 10 月 3 日釋出，我們很高興地報告，現在我們已經有許多符合規範的實現供大家試用。

Gateway API v1.2 為 Standard channel（Gateway API 的 GA 釋出渠道）帶來了許多新功能，引入了一些新的實驗性功能，並開啟了我們新的釋出流程——但它也帶來了兩個你需要注意的重大變更。

重大變更

移除 GRPCRoute 和 ReferenceGrant 的 v1alpha2 版本

既然 GRPCRoute 和 ReferenceGrant 的 v1 版本已經畢業到 Standard 級別，舊的 v1alpha2 版本已從 Standard 和 Experimental 渠道中移除，以減輕 Gateway API 社群因永久支援舊版本而產生的維護負擔。

在升級到 Gateway API v1.2 之前，你需要確認所有 Gateway API 的實現都已升級，以支援這些資源的 v1 API 版本，而不是 v1alpha2 API 版本。請注意，即使你一直在 YAML 清單中使用 v1，控制器可能仍在使用 v1alpha2，這會導致它在升級過程中失敗。此外，Kubernetes 本身會盡力阻止你移除它認為你正在使用的 CRD 版本：請查閱釋出說明以獲取有關安全升級所需操作的更多資訊。

.status.supportedFeatures 變更（實驗性）

一個較小的重大變更：Gateway 中的 .status.supportedFeatures 現在是一個物件列表，而不是字串列表。這些物件有一個名為 name 的欄位，因此從字串轉換過來很簡單，但遷移到物件為未來提供了更大的靈活性。這個欄位尚未出現在 Standard 渠道中。

畢業到 Standard 渠道的功能

Gateway API 1.2.0 將四個功能畢業到 Standard 渠道，這意味著它們現在可以被視為正式可用。被納入 Standard 釋出渠道表明了對 API 介面的高度信心，並提供了向後相容性的保證。當然，與任何其他 Kubernetes API 一樣，Standard 渠道的功能可以隨著時間的推移，透過向後相容的增加而繼續演進，我們當然期望未來對這些新功能進行進一步的完善和改進。有關這一切如何運作的更多資訊，請參閱 Gateway API 版本控制策略。

HTTPRoute 超時

GEP-1742 在 HTTPRoute 中引入了 timeouts 欄位，允許為 HTTP 流量配置基本超時。這是在處理 HTTP 流量時實現適當彈性的一個簡單但重要的功能，現在它已成為 Standard 功能。

例如，此 HTTPRoute 配置為到 /face 路徑的流量設定了 300 毫秒的超時

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: face-with-timeouts
  namespace: faces
spec:
  parentRefs:
    - name: my-gateway
      kind: Gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /face
    backendRefs:
    - name: face
      port: 80
    timeouts:
      request: 300ms

更多資訊，請查閱 HTTP 路由文件。（請注意，這僅適用於 HTTPRoute 超時。GRPCRoute 超時尚未成為 Gateway API 的一部分。）

Gateway 基礎設施標籤和註解

Gateway API 的實現負責建立使每個 Gateway 工作所需的底層基礎設施。例如，在 Kubernetes 叢集中執行的實現通常會建立 Service 和 Deployment，而基於雲的實現可能會建立雲負載均衡器資源。在許多情況下，能夠將標籤或註解傳播到這些生成的資源會很有幫助。

在 v1.2.0 中，Gateway 的 infrastructure 欄位移至 Standard 渠道，允許你為 Gateway API 控制器建立的基礎設施指定標籤和註解。例如，如果你的 Gateway 基礎設施在叢集內執行，你可以使用以下 Gateway 配置同時指定 Linkerd 和 Istio 注入，從而更輕鬆地將基礎設施整合到你已安裝的任何服務網格中

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: meshed-gateway
  namespace: incoming
spec:
  gatewayClassName: meshed-gateway-class
  listeners:
  - name: http-listener
    protocol: HTTP
    port: 80
  infrastructure:
    labels:
      istio-injection: enabled
    annotations:
      linkerd.io/inject: enabled

更多資訊，請查閱 infrastructure API 參考。

後端協議支援

自 Kubernetes v1.20 以來，Service 和 EndpointSlice 資源支援一個穩定的 appProtocol 欄位，允許使用者指定 Service 支援的 L7 協議。隨著 KEP 3726 的採納，Kubernetes 現在支援三個新的 appProtocol 值

kubernetes.io/h2c

如 RFC7540 中所述的明文 HTTP/2

kubernetes.io/ws

如 RFC6445 中所述的明文 WebSocket

kubernetes.io/wss

如 RFC6445 中所述的 TLS WebSocket

在 Gateway API 1.2.0 中，對 appProtocol 的支援現已成為 Standard 功能。例如，給定以下 Service

apiVersion: v1
kind: Service
metadata:
  name: websocket-service
  namespace: my-namespace
spec:
  selector:
    app.kubernetes.io/name: websocket-app
  ports:
    - name: http
      port: 80
      targetPort: 9376
      protocol: TCP
      appProtocol: kubernetes.io/ws

那麼，一個將此 Service 作為 backendRef 包含的 HTTPRoute 將自動升級連線以使用 WebSocket，而不是假定連線是純 HTTP。

更多資訊，請查閱 GEP-1911。

Experimental 渠道新增功能

為 *Route 資源命名規則

HTTPRoute 和 GRPCRoute 資源中的 rules 欄位現在可以命名，以便更容易地引用特定規則，例如

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: multi-color-route
  namespace: faces
spec:
  parentRefs:
    - name: my-gateway
      kind: Gateway
      port: 80
  rules:
  - name: center-rule
    matches:
    - path:
        type: PathPrefix
        value: /color/center
    backendRefs:
    - name: color-center
      port: 80
  - name: edge-rule
    matches:
    - path:
        type: PathPrefix
        value: /color/edge
    backendRefs:
    - name: color-edge
      port: 80

日誌記錄或狀態訊息現在可以將這兩個規則稱為 center-rule 或 edge-rule，而不必透過索引來引用它們。更多資訊，請參見 GEP-995。

HTTPRoute 重試支援

Gateway API 1.2.0 引入了對 HTTPRoute 計次重試的實驗性支援。例如，以下 HTTPRoute 配置對到 /face 路徑的請求重試最多 3 次，每次重試之間有 500 毫秒的延遲

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: face-with-retries
  namespace: faces
spec:
  parentRefs:
    - name: my-gateway
      kind: Gateway
      port: 80
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /face
    backendRefs:
    - name: face
      port: 80
    retry:
      codes: [ 500, 502, 503, 504 ]
      attempts: 3
      backoff: 500ms

更多資訊，請查閱 GEP 1731。

HTTPRoute 基於百分比的流量映象

Gateway API 長期以來一直支援請求映象功能，該功能允許將相同的請求傳送到多個後端。在 Gateway API 1.2.0 中，我們引入了基於百分比的映象，允許你指定要映象到不同後端的請求百分比。例如，以下 HTTPRoute 配置將 42% 的請求映象到 color-mirror 後端

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: color-mirror-route
  namespace: faces
spec:
  parentRefs:
  - name: mirror-gateway
  hostnames:
  - mirror.example
  rules:
  - backendRefs:
    - name: color
      port: 80
    filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: color-mirror
          port: 80
        percent: 42   # This value must be an integer.

還有一個 fraction 欄位，可以用來代替 percent，以便更精確地控制映象的流量量，例如

    ...
    filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: color-mirror
          port: 80
        fraction:
          numerator: 1
          denominator: 10000

此配置將每 10,000 個請求中的 1 個映象到 color-mirror 後端，這在請求率非常高的情況下可能很有用。更多詳情，請參見 GEP-1731。

額外的後端 TLS 配置

此版本包含了三項與 Gateway 和工作負載（後端）之間通訊的 TLS 配置相關的補充

1. Gateway 上新增 backendTLS 欄位

   這個新欄位允許你指定 Gateway 連線到後端時應使用的客戶端證書。

2. BackendTLSPolicy 上新增 subjectAltNames 欄位

   以前，hostname 欄位用於配置 Gateway 應傳送給後端的 SNI 以及 證書應提供的身份。當指定新的 subjectAltNames 欄位時，任何匹配至少一個指定 SANs 的證書都將被視為有效。這對於 SPIFFE 尤其關鍵，因為基於 URI 的 SANs 可能不是有效的 SNI。

3. BackendTLSPolicy 上新增 options 欄位

   與 Gateway Listener 上的 TLS 選項欄位類似，我們相信同樣的概念將廣泛適用於後端的 TLS 特定配置。

更多資訊，請查閱 GEP-3135。

更多變更

有關此版本中包含的變更的完整列表，請參閱 v1.2.0 釋出說明。

專案更新

除了技術層面，v1.2 版本也標誌著 Gateway API 專案本身發展過程中的幾個里程碑。

釋出流程改進

Gateway API 從未打算成為一個靜態 API，隨著越來越多的專案將其用作構建基礎，我們顯然需要為 Gateway API 的釋出帶來更多的可預測性。為此，我們很高興——也有些緊張！——地宣佈，我們已經正式確定了一個新的釋出流程

• 範圍確定（4-6 周）：維護者和社群確定我們希望在版本中包含的功能集。這裡的一個特別重點是將功能從 Experimental 渠道中“移出”——理想情況下是將其移至 Standard，但也可能意味著移除它們。

• GEP 迭代與審查（5-7 周）：貢獻者為被接納到版本中的功能編寫或更新 Gateway 增強提案（GEP），重點是圍繞功能的設計和畢業標準達成共識。

• API 完善與文件編寫（3-5 周）：貢獻者在 Gateway API 控制器中實現功能並編寫必要的文件。

• SIG Network 審查與釋出候選版本（2-4 周）：維護者獲得所需的上游審查，構建釋出候選版本，併發布新版本。

Gateway API 1.2.0 是第一個使用新流程的釋出版本，儘管任何新事物都有其常見的粗糙之處，但我們相信它進行得很順利。我們已經完成了 Gateway API 1.3 的範圍確定階段，預計釋出時間在 2025 年 1 月底左右。

gwctl 移出

gwctl CLI 工具已移至其自己的倉庫：https://github.com/kubernetes-sigs/gwctl。gwctl 已被證明是 Gateway API 社群的一個寶貴工具；我們相信，將其移至自己的倉庫將使其更易於維護和開發。一如既往，我們歡迎貢獻；雖然仍處於實驗階段，但 gwctl 已經幫助使與 Gateway API 的協作變得更容易一些——特別是對於專案的新手來說！

維護者變更

作為對專案本身變更的補充，我們很高興地宣佈 Mattia Lavacca 已加入 Gateway API 維護者行列！我們也很遺憾地宣佈 Keith Mattix 已卸任 GAMMA 負責人——令人高興的是，Mike Morris 已重返該職位。我們感謝 Keith 所做的一切，並對 Mattia 和 Mike 的加入感到興奮。

立即試用

與其他 Kubernetes API 不同，你無需升級到最新版本的 Kubernetes 即可獲得最新版本的 Gateway API。只要你執行的是 Kubernetes 1.26 或更高版本，你就能使用此版本的 Gateway API。

要試用該 API，請遵循我們的入門指南。截至本文撰寫時，已有五個實現符合 Gateway API v1.2 的規範。按字母順序排列

• Cilium v1.17.0-pre.1，Experimental 渠道
• Envoy Gateway v1.2.0-rc.1，Experimental 渠道
• Istio v1.24.0-alpha.0，Experimental 渠道
• Kong v3.2.0-244-gea4944bb0，Experimental 渠道
• Traefik v3.2，Experimental 渠道

參與其中

有很多機會可以參與進來，幫助定義 Kubernetes 路由 API 在入口和服務網格方面的未來。

• 檢視使用者指南，瞭解可以解決哪些用例。
• 試用現有的 Gateway 控制器之一。
• 或者加入我們的社群，幫助我們共同構建 Gateway API 的未來！

維護者們要感謝為 Gateway API 做出貢獻的每一個人，無論是以倉庫提交、討論、想法還是普遍支援的形式。沒有這個敬業且活躍的社群的支援，我們永遠不可能走到今天這一步。

相關 Kubernetes 部落格文章

• Gateway API v1.1：服務網格、GRPCRoute 以及更多
• Gateway API v1.0 中的新實驗性功能 11/2023
• Gateway API v1.0: GA 版本 10/2023
• 介紹 ingress2gateway；簡化到 Gateway API 的升級 10/2023
• Gateway API v0.8.0：引入服務網格支援 08/2023

• ←上一篇
• 下一篇→