本文已超過一年。較舊的文章可能包含過時的內容。請檢查頁面中的資訊自發布以來是否已變得不正確。

Gateway API v1.0 中的新實驗性功能

作者：Candace Holman (Red Hat), Dave Protasowski (VMware), Gaurav K Ghildiyal (Google), John Howard (Google), Simone Rodigari (IBM) | 2023 年 11 月 28 日，星期二

最近，Gateway API 宣布其 v1.0 GA 版本，標誌著該專案的一個重大里程碑。

除了穩定 API 中的一些核心功能外，還新增了許多令人興奮的實驗性功能。

後端 TLS 政策

BackendTLSPolicy 是一種新的 Gateway API 類型，用於指定從 Gateway 透過 Service API 物件到後端 Pod 的連線之 TLS 組態。它被指定為 Direct PolicyAttachment，不含預設值或覆寫，應用於存取後端的 Service，其中 BackendTLSPolicy 與其套用的 Service 位於相同的命名空間中。所有指向參照 Service 的 Gateway API 路由都應遵循已設定的 BackendTLSPolicy。

雖然現有方法提供了用於為邊緣和 passthrough 終止設定 TLS，但這個新的 API 物件專門解決 TLS 的組態問題，以便從 Gateway 資料平面傳輸 HTTPS 到後端。這稱為「後端 TLS 終止」，讓 Gateway 知道如何連線到具有自身憑證的後端 Pod。

Termination Types

BackendTLSPolicy 的規格包含

targetRef - 定義政策的目標 API 物件。僅允許 Service。
tls - 定義 TLS 的組態，包括 hostname、caCertRefs 和 wellKnownCACerts。可以指定 caCertRefs 或 wellKnownCACerts，但不能同時指定兩者。
hostname - 定義 Gateway 用於連線到後端的伺服器名稱指示 (SNI)。後端提供的憑證必須符合此 SNI。
caCertRefs - 定義對一或多個包含 PEM 編碼 TLS 憑證之物件的參照，這些憑證用於在 Gateway 和後端之間建立 TLS 交握。
wellKnownCACerts - 指定是否可以在 Gateway 和後端之間的 TLS 交握中使用系統 CA 憑證。

範例

使用系統憑證

在此範例中，BackendTLSPolicy 組態為使用系統憑證連線到 TLS 加密的上游連線，其中支援 dev Service 的 Pod 預期會為 dev.example.com 提供有效的憑證。

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendTLSPolicy
metadata:
  name: tls-upstream-dev
spec:
  targetRef:
    kind: Service
    name: dev-service
    group: ""
  tls:
    wellKnownCACerts: "System"
    hostname: dev.example.com

使用明確 CA 憑證

在此範例中，BackendTLSPolicy 組態為使用組態地圖 auth-cert 中定義的憑證連線到 TLS 加密的上游連線，其中支援 auth Service 的 Pod 預期會為 auth.example.com 提供有效的憑證。

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendTLSPolicy
metadata:
  name: tls-upstream-auth
spec:
  targetRef:
    kind: Service
    name: auth-service
    group: ""
  tls:
    caCertRefs:
      - kind: ConfigMapReference
        name: auth-cert
        group: ""
    hostname: auth.example.com

以下說明為服務後端的 Service 設定 TLS 的 BackendTLSPolicy

flowchart LR client(["client"]) gateway["Gateway"] style gateway fill:#02f,color:#fff httproute["HTTP
Route"] style httproute fill:#02f,color:#fff service["Service"] style service fill:#02f,color:#fff pod1["Pod"] style pod1 fill:#02f,color:#fff pod2["Pod"] style pod2 fill:#02f,color:#fff client -.->|HTTP
request| gateway gateway --> httproute httproute -.->|BackendTLSPolicy|service service --> pod1 & pod2

如需更多資訊，請參閱 TLS 文件。

HTTPRoute 超時

Gateway API 最新版本 (v1.0) 的主要增強功能是在 HTTPRoute 規則中引入 timeouts 欄位。此功能提供了一種動態方式來管理傳入 HTTP 請求的超時，為您的閘道設定增加了精確性和可靠性。

透過超時，開發人員可以透過兩種基本方式微調其 Gateway API 的行為

請求超時:
請求超時是 Gateway API 實作必須在其中將回應傳送至用戶端 HTTP 請求的持續時間。它允許彈性地指定此超時何時開始，可以在接收整個用戶端請求串流之前或之後，使其成為實作特定的。此超時有效地涵蓋了整個請求-回應交易，從而增強了服務的回應能力。
後端請求超時:
對於處理後端的人員來說，backendRequest 超時是一項重大變革。它為從 Gateway 傳送到後端服務的單個請求設定了超時。此超時範圍從請求的啟動到接收來自後端的完整回應。此功能在 Gateway 需要重試與後端的連線的情況下特別有用，從而確保在各種條件下都能順暢通訊。

值得注意的是，request 超時包含 backendRequest 超時。因此，backendRequest 的值永遠不應超過 request 超時的值。

設定這些超時的能力為您的 Kubernetes 服務增加了一層新的可靠性。無論是確保在指定時間範圍內處理用戶端請求，還是管理後端服務通訊，Gateway API 的超時都提供了您需要的控制和可預測性。

若要開始使用，您可以使用 Timeouts 欄位在 HTTPRoute 規則中定義超時，並將其類型指定為 Duration。零值超時 (0s) 會停用超時，而有效的非零值超時應至少為 1 毫秒。

以下是在 HTTPRoute 中設定 request 和 backendRequest 超時的範例

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: timeout-example
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /timeout
    timeouts:
      request: 10s
      backendRequest: 2s
    backendRefs:
    - name: timeout-svc
      port: 8080

在此範例中，定義了 10 秒的 request 超時，以確保在此時間範圍內處理用戶端請求。此外，為從 Gateway 到名為 timeout-svc 的後端服務的個別請求設定了 2 秒的 backendRequest 超時。

這些新的 HTTPRoute 超時為 Kubernetes 使用者提供了更多控制和彈性來管理網路通訊，從而協助確保為用戶端和後端提供更順暢、更可預測的體驗。如需更多詳細資訊和範例，請參閱官方超時 API 文件。

Gateway 基礎架構標籤

雖然 Gateway API 為不同的實作提供了一個通用的 API，但每個實作都會有不同的底層資源被建立，以應用使用者的意圖。這可能包括設定雲端負載平衡器、建立叢集內 Pod 和 Service 等。

雖然 API 一直以來都提供了一個擴充點 - GatewayClass 中的 parametersRef - 用於自訂實作特定的事物，但沒有通用的核心方法來表達常見的基礎架構自訂。

Gateway API v1.0 為此鋪路，在 Gateway 物件上新增了 infrastructure 欄位，允許自訂底層基礎架構。目前，這從兩個關鍵欄位開始：標籤和註釋。設定這些欄位後，任何產生的基礎架構都將設定提供的標籤和註釋。

例如，我可能想要將一個應用程式的所有資源分組在一起

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: hello-world
spec:
  infrastructure:
    labels:
      app.kubernetes.io/name: hello-world

未來，我們正在研究更多常見的基礎架構組態，例如資源大小調整。

如需更多資訊，請參閱此功能的文件。

支援 Websocket、HTTP/2 和更多功能！

並非所有 Gateway API 的實作都支援自動協定選擇。在某些情況下，協定會在沒有明確選擇加入的情況下停用。

當 Route 的後端參照 Kubernetes Service 時，應用程式開發人員可以使用 ServicePort appProtocol 欄位指定協定。

例如，以下 store Kubernetes Service 指出連接埠 8080 支援 HTTP/2 Prior Knowledge。

apiVersion: v1
kind: Service
metadata:
  name: store
spec:
  selector:
    app: store
  ports:
  - protocol: TCP
    appProtocol: kubernetes.io/h2c
    port: 8080
    targetPort: 8080

目前，Gateway API 具有以下項目的一致性測試

kubernetes.io/h2c - HTTP/2 Prior Knowledge
kubernetes.io/ws - WebSocket over HTTP

如需更多資訊，請參閱後端協定選擇文件。

`gwctl`，我們新的 Gateway API 命令列工具

gwctl 是一個命令列工具，旨在成為用於檢視 Gateway API 資源的 kubectl 替代方案。

與 Gateway v1.0 版本捆綁在一起的 gwctl 初始版本包含用於管理 Gateway API 政策的實用功能。Gateway API 政策充當強大的擴充機制，用於修改 Gateway 資源的行為。使用政策的一個挑戰可能是很難發現哪些政策正在影響哪些 Gateway 資源。gwctl 透過回答以下問題來協助彌合此差距

哪些政策可用於 Kubernetes 叢集？
哪些政策附加到特定的 Gateway、HTTPRoute 等？
如果政策應用於 Gateway 資源階層中的多個資源，則影響特定資源的有效政策是什麼？（例如，如果 HTTP 請求超時政策同時應用於 HTTPRoute 及其父 Gateway，則 HTTPRoute 的有效超時是多少？）

gwctl 仍處於非常早期的開發階段，因此可能有點粗糙。請依照儲存庫中的指示安裝並試用 gwctl。

範例

以下是一些 gwctl 如何使用的範例

# List all policies in the cluster. This will also give the resource they bind
# to.
gwctl get policies -A
# List all available policy types.
gwctl get policycrds
# Describe all HTTPRoutes in namespace ns2. (Output includes effective policies)
gwctl describe httproutes -n ns2
# Describe a single HTTPRoute in the default namespace. (Output includes
# effective policies)
gwctl describe httproutes my-httproute-1
# Describe all Gateways across all namespaces. (Output includes effective
# policies)
gwctl describe gateways -A
# Describe a single GatewayClass. (Output includes effective policies)
gwctl describe gatewayclasses foo-com-external-gateway-class

參與其中

這些專案以及更多專案在 Gateway API 中持續改進。有很多機會可以參與並協助定義 Kubernetes 路由 API 的未來，適用於 Ingress 和 Mesh。

如果您對此感興趣，請加入我們的社群，並協助我們共同建構 Gateway API 的未來！