Gateway API v1.2：WebSockets、逾時、重試及更多功能

由 Gateway API 貢獻者 | 週四，2024 年 11 月 21 日

Kubernetes SIG Network 很高興宣布 Gateway API v1.2 正式發布！此 API 版本於 10 月 3 日發布，我們很高興地宣布，我們現在有許多符合規範的實作供您試用。

Gateway API v1.2 為標準通道（Gateway API 的 GA 發布通道）帶來了許多新功能，引入了一些新的實驗性功能，並啟用了我們新的發布流程——但它也帶來了兩個重大變更，您需要注意。

重大變更

GRPCRoute 和 ReferenceGrant `v1alpha2` 移除

現在 GRPCRoute 和 ReferenceGrant 的 v1 版本已升級為標準版，舊的 v1alpha2 版本已從標準通道和實驗性通道中移除，以減輕永久支援舊版本將給 Gateway API 社群帶來的維護負擔。

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

變更為 `.status.supportedFeatures`（實驗性）

一個小得多的重大變更：Gateway 中的 .status.supportedFeatures 現在是物件列表，而不是字串列表。物件有一個單一的 name 欄位，因此從字串的轉換很簡單，但移動到物件允許未來有更大的彈性。此節目前尚未出現在標準通道中。

升級到標準通道

Gateway API 1.2.0 將四個功能升級到標準通道，這意味著它們現在可以被認為是正式發布。包含在標準發布通道中表示對 API 表面有高度信心，並提供向後相容性的保證。當然，與任何其他 Kubernetes API 一樣，標準通道功能可以隨著時間的推移透過向後相容的添加繼續發展，我們當然期望在未來對這些新功能進行進一步的改進和完善。有關所有這些如何運作的更多資訊，請參閱Gateway API 版本控制策略。

HTTPRoute 超時

GEP-1742 將 timeouts 節引入 HTTPRoute，允許為 HTTP 流量配置基本超時。這是一個簡單但重要的功能，用於在處理 HTTP 流量時實現適當的彈性，現在已成為標準。

例如，此 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 叢集中運行的實作通常會建立服務和部署，而基於雲端的實作可能會建立雲端負載平衡器資源。在許多情況下，能夠將標籤或註解傳播到這些產生的資源可能會有所幫助。

在 v1.2.0 中，Gateway infrastructure 節移至標準通道，允許您為 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，如 RFC7540 中所述
kubernetes.io/ws: RFC6445 中描述的基於明文的 WebSocket，如 RFC6445 中所述
kubernetes.io/wss: RFC6445 中描述的基於 TLS 的 WebSocket，如 RFC6445 中所述

透過 Gateway API 1.2.0，對遵守 appProtocol 的支援現在已成為標準。例如，給定以下 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 將自動升級連線以使用 WebSockets，而不是假設連線是純 HTTP。

有關更多資訊，請查看GEP-1911。

實驗性通道的新增功能

*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

此配置將 1/10,000 的請求鏡像到 color-mirror 後端，這可能與非常高的請求速率相關。有關更多詳細資訊，請參閱GEP-1731。

其他後端 TLS 配置

此版本包含三個與 Gateway 和工作負載（後端）之間通訊的 TLS 配置相關的新增功能

Gateway 上新的 backendTLS 欄位
這個新欄位允許您指定 Gateway 在連線到後端時應使用的用戶端憑證。
BackendTLSPolicy 上新的 subjectAltNames 欄位
以前，hostname 欄位用於配置 Gateway 應發送到後端的 SNI 以及憑證應提供的身分。當指定新的 subjectAltNames 欄位時，任何符合至少一個指定 SAN 的憑證都將被視為有效。這對於 SPIFFE 尤其重要，在 SPIFFE 中，基於 URI 的 SAN 可能不是有效的 SNI。
BackendTLSPolicy 上新的 options 欄位
與 Gateway Listener 上的 TLS 選項欄位類似，我們相信相同的概念對於後端 TLS 的 TLS 特定配置將廣泛有用。

有關更多資訊，請查看GEP-3135。

專案更新

除了技術方面，v1.2 發行版本還標誌著 Gateway API 專案本身生命週期中的幾個里程碑。

發布流程改進

Gateway API 從未打算成為靜態 API，並且隨著越來越多的專案將其用作構建基礎的組件，很明顯我們需要為 Gateway API 發布帶來更多可預測性。為此，我們很高興 - 並且有點緊張！- 地宣布我們已正式確定新的發布流程

範圍界定（4-6 週）：維護者和社群確定我們想要包含在發行版本中的功能集。此處特別強調的是將功能移出實驗性通道——理想情況下，這涉及將它們移至標準版，但也可能意味著移除它們。
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，實驗性通道
Envoy Gateway v1.2.0-rc.1，實驗性通道
Istio v1.24.0-alpha.0，實驗性通道
Kong v3.2.0-244-gea4944bb0，實驗性通道
Traefik v3.2，實驗性通道

參與其中

有很多機會可以參與並協助定義 Kubernetes 路由 API 的未來，無論是針對 Ingress 還是服務網格。

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

維護者要感謝每一位為 Gateway API 做出貢獻的人，無論是以提交到儲存庫、討論、想法或一般支援的形式。如果沒有這個敬業且活躍的社群的支持，我們永遠無法走到這一步。

Kubernetes 部落格

Gateway API v1.2：WebSockets、逾時、重試及更多功能

重大變更

GRPCRoute 和 ReferenceGrant `v1alpha2` 移除

變更為 `.status.supportedFeatures`（實驗性）

升級到標準通道

HTTPRoute 超時

Gateway 基礎架構標籤和註解

後端協議支援

實驗性通道的新增功能

*Route 資源的命名規則

HTTPRoute 重試支援

HTTPRoute 基於百分比的鏡像

其他後端 TLS 配置

更多變更

專案更新

發布流程改進

`gwctl` 移出

維護者變更

試用看看

參與其中

Gateway API v1.2：WebSockets、逾時、重試及更多功能

重大變更

GRPCRoute 和 ReferenceGrant v1alpha2 移除

變更為 .status.supportedFeatures（實驗性）

升級到標準通道

HTTPRoute 超時

Gateway 基礎架構標籤和註解

後端協議支援

實驗性通道的新增功能

*Route 資源的命名規則

HTTPRoute 重試支援

HTTPRoute 基於百分比的鏡像

其他後端 TLS 配置

更多變更

專案更新

發布流程改進

gwctl 移出

維護者變更

試用看看

參與其中

相關的 Kubernetes 博客文章

GRPCRoute 和 ReferenceGrant `v1alpha2` 移除

變更為 `.status.supportedFeatures`（實驗性）

`gwctl` 移出