Gateway API v1.3.0：請求映象、CORS、網關合並和重試預算方面的進展

歡迎與 Kubernetes SIG Network 社群一起，慶祝 Gateway API v1.3.0 正式釋出！我們也很高興地宣佈，由於推遲了這篇部落格的釋出，已經有許多符合標準的實現可供嘗試。API 的 1.3.0 版本已於大約一個月前的 2025 年 4 月 24 日釋出。

Gateway API v1.3.0 為*標準（Standard）*頻道（Gateway API 的 GA 釋出頻道）帶來了新功能：*基於百分比的請求映象*，並引入了三項新的實驗性功能：跨源資源共享（CORS）過濾器、監聽器和網關合並的標準化機制以及重試預算。

另請參閱完整的發行說明，下次見到 v1.3.0 釋出團隊時，請為他們喝彩。

升級到 Standard 頻道

升級到 Standard 頻道是 Gateway API 功能的一項顯著成就，因為被納入 Standard 釋出頻道意味著對 API 介面的高度信心，並提供了向後相容性的保證。當然，與任何其他 Kubernetes API 一樣，Standard 頻道的功能可以透過向後相容的增補不斷演進，我們（SIG Network）當然期望未來會有進一步的完善和改進。有關其工作原理的更多資訊，請參閱 Gateway API 版本控制策略。

基於百分比的請求映象

負責人：Lior Lieberman、Jake Bennert

GEP-3171：基於百分比的請求映象

基於百分比的請求映象是對現有HTTP 請求映象支援的增強，它允許使用 RequestMirror 過濾器型別將 HTTP 請求複製到另一個後端。請求映象在藍綠部署中特別有用。它可以用來評估請求擴充套件對應用程式效能的影響，而不會影響對客戶端的響應。

之前的映象功能對所有到 backendRef 的請求都有效。
基於百分比的請求映象允許使用者指定他們希望映象的請求子集，可以按百分比或分數。當服務接收到大量請求時，這尤其有用。這個新功能可以用來映象其中的一小部分，而不是映象所有這些請求。

這是一個例子，其中 42% 的到“foo-v1”的請求被映象到“foo-v2”

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-filter-mirror
  labels:
    gateway: mirror-gateway
spec:
  parentRefs:
  - name: mirror-gateway
  hostnames:
  - mirror.example
  rules:
  - backendRefs:
    - name: foo-v1
      port: 8080
    filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: foo-v2
          port: 8080
        percent: 42 # This value must be an integer.

你還可以使用分數來配置部分映象。這是一個例子，其中每 1000 個到“foo-v1”的請求中有 5 個被映象到“foo-v2”。

  rules:
  - backendRefs:
    - name: foo-v1
      port: 8080
    filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: foo-v2
          port: 8080
        fraction:
          numerator: 5
          denominator: 1000

Experimental 頻道的新增內容

Experimental 頻道是 Gateway API 用於試驗新功能並在其升級到 Standard 頻道之前建立信心的渠道。請注意：Experimental 頻道可能包含之後會更改或刪除的功能。

從 v1.3.0 版本開始，為了區分 Experimental 頻道資源和 Standard 頻道資源，任何新的實驗性 API kind 都帶有字首“X”。出於同樣的原因，實驗性資源現在被新增到 API 組 gateway.networking.x-k8s.io 而不是 gateway.networking.k8s.io。請記住，使用新的 Experimental 頻道資源意味著它們可以與 Standard 頻道資源共存，但將這些資源遷移到 Standard 頻道將需要使用 Standard 頻道的名稱和 API 組（兩者都沒有“x-k8s”指示符或“X”字首）重新建立它們。

v1.3 版本引入了兩個新的實驗性 API kind：XBackendTrafficPolicy 和 XListenerSet。要使用實驗性 API kind，你需要從下面列出的位置安裝 Experimental 頻道的 Gateway API YAML 檔案。

CORS 過濾

負責人：Liang Li、Eyal Pazz、Rob Scott

GEP-1767：CORS 過濾器

跨源資源共享（CORS）是一種基於 HTTP 標頭的機制，它允許網頁從一個不同於提供該網頁的域的源（域、協議或埠）的伺服器訪問受限資源。此功能添加了一個新的 HTTPRoute filter 型別，稱為“CORS”，用於在將響應傳送回客戶端之前配置跨源請求的處理。

要使用實驗性的 CORS 過濾，你需要安裝Experimental 頻道的 Gateway API HTTPRoute yaml。

這是一個簡單跨源配置的例子

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-route-cors
spec:
  parentRefs:
  - name: http-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /resource/foo
    filters:
    - cors:
      - type: CORS
        allowOrigins:
        - *
        allowMethods: 
        - GET
        - HEAD
        - POST
        allowHeaders: 
        - Accept
        - Accept-Language
        - Content-Language
        - Content-Type
        - Range
    backendRefs:
    - kind: Service
      name: http-route-cors
      port: 80

在這種情況下，閘道器返回一個“*”的*源標頭*，這意味著請求的資源可以從任何源引用，一個允許 GET、HEAD 和 POST 動詞的*方法標頭*（Access-Control-Allow-Methods），以及一個允許 Accept、Accept-Language、Content-Language、Content-Type 和 Range 的*標頭*。

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, POST
Access-Control-Allow-Headers: Accept,Accept-Language,Content-Language,Content-Type,Range

新的 CORS 過濾器中的完整欄位列表

• allowOrigins
• allowMethods
• allowHeaders
• allowCredentials
• exposeHeaders
• maxAge

有關詳細資訊，請參閱 CORS 協議。

XListenerSets（監聽器和網關合並的標準化機制）

負責人：Dave Protasowski

GEP-1713：ListenerSets - 合併多個閘道器的標準機制

此版本添加了一個新的實驗性 API kind，XListenerSet，它允許將共享的*監聽器*列表附加到一個或多個父閘道器。此外，它擴充套件了現有的建議，即 Gateway API 實現可以合併來自多個 Gateway 物件的配置。它還

• 在閘道器的 .spec 中添加了一個新欄位 allowedListeners。allowedListeners 欄位定義了從哪些名稱空間選擇允許附加到該閘道器的 XListenerSet：Same、All、None 或基於 Selector。
• 透過增加 XListenerSet，增加了先前監聽器的最大數量（64）。
• 允許將監聽器配置（如 TLS）委託給其他名稱空間中的應用程式。

要使用實驗性的 XListenerSet，你需要安裝Experimental 頻道的 Gateway API XListenerSet yaml。

以下示例顯示了一個帶有 HTTP 監聽器和兩個具有唯一主機名和證書的子 HTTPS XListenerSet 的閘道器。附加到閘道器的監聽器組合包括附加到閘道器的 XListenerSet 中的兩個附加 HTTPS 監聽器。此示例說明了將監聽器 TLS 配置委託給不同名稱空間（“store”和“app”）中的應用程式所有者。HTTPRoute 將名為“foo”的閘道器監聽器和名為“second”的 XListenerSet 監聽器都作為 parentRefs。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-external
  namespace: infra
spec:
  gatewayClassName: example
  allowedListeners:
  - from: All
  listeners:
  - name: foo
    hostname: foo.com
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XListenerSet
metadata:
  name: store
  namespace: store
spec:
  parentRef:
    name: prod-external
  listeners:
  - name: first
    hostname: first.foo.com
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        group: ""
        name: first-workload-cert
---
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XListenerSet
metadata:
  name: app
  namespace: app
spec:
  parentRef:
    name: prod-external
  listeners:
  - name: second
    hostname: second.foo.com
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        group: ""
        name: second-workload-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httproute-example
spec:
  parentRefs:
  - name: app
    kind: XListenerSet
    sectionName: second
  - name: parent-gateway
    kind: Gateway
    sectionName: foo
    ...

閘道器中的每個監聽器都必須具有唯一的 port、protocol（以及協議支援的 hostname）組合，以便所有監聽器都*相容*且不會在它們應該接收的流量上發生衝突。

此外，如果跨多個閘道器的所有監聽器都相容，實現可以*合併*單獨的閘道器為一組監聽器地址。在 v1.3.0 之前的版本中，合併監聽器的管理規定不足。

有了新功能，合併的規範得到了擴充套件。實現必須將父閘道器視為擁有其自身和附加的 XListenerSet 的所有監聽器的合併列表，並且此監聽器列表的驗證必須與該列表是單個閘道器的一部分時一樣。在單個閘道器內，監聽器按以下優先順序排序

1. 首先是單個監聽器（不屬於 XListenerSet），
2. 其餘監聽器按
   • 物件建立時間（最早的優先）排序，如果兩個監聽器在具有相同時間戳的物件中定義，則
   • 按“{namespace}/{name of listener}”的字母順序排序

重試預算（XBackendTrafficPolicy）

負責人：Eric Bishop、Mike Morris

GEP-3388：重試預算

此功能允許你為目標服務的所有端點配置*重試預算*。這用於在達到配置的閾值後限制額外的客戶端重試。在配置預算時，可以指定可能由重試組成的活動請求的最大百分比，以及在計算重試閾值時將考慮請求的時間間隔。此規範的開發將現有的實驗性 API kind BackendLBPolicy 更改為新的實驗性 API kind XBackendTrafficPolicy，以減少具有共性的策略資源的擴散。

要使用實驗性的重試預算，你需要安裝Experimental 頻道的 Gateway API XBackendTrafficPolicy yaml。

以下示例顯示了一個應用 retryConstraint 的 XBackendTrafficPolicy，該約束表示一個預算，它將重試限制為請求的最大 20%，持續時間為 10 秒，並且在 1 秒內至少有 3 次重試。

apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XBackendTrafficPolicy
metadata:
  name: traffic-policy-example
spec:
  retryConstraint:
    budget: 
        percent: 20
        interval: 10s
    minRetryRate:
      count: 3
      interval: 1s
    ...

立即試用

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

要試用該 API，請遵循入門指南。截至本文撰寫時，已有四個實現符合 Gateway API v1.3 實驗性頻道的功能。按字母順序排列

• Airlock Microgateway 4.6
• Cilium main
• Envoy Gateway v1.4.0
• Istio 1.27-dev

參與其中

想知道某個功能何時會新增嗎？有很多機會可以參與進來，幫助定義 Kubernetes 路由 API（用於入口和服務網格）的未來。

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

維護者們想感謝*每一位*為 Gateway API 做出貢獻的人，無論是以向倉庫提交程式碼、討論、提出想法還是提供一般支援的形式。沒有這個敬業而活躍的社群的支援，我們永遠不可能取得如此大的進步。

相關 Kubernetes 部落格文章

• Gateway API v1.2：WebSockets、超時、重試等 (2024 年 11 月)
• Gateway API v1.1：服務網格、GRPCRoute 以及更多 (2024 年 5 月)
• Gateway API v1.0 中的新實驗性功能 (2023 年 11 月)
• Gateway API v1.0：GA 釋出 (2023 年 10 月)

• ←上一篇
• 下一篇→