Kubernetes Gateway API 教學：取代 Ingress 流量管理

Ingress 要退場了，你準備好了嗎？

如果你正在用 ingress-nginx 管理 Kubernetes 的流量，這邊有個壞消息要告訴你：ingress-nginx 官方已經宣佈在 2026 年 3 月停止維護，不再有新版本、bug 修復，甚至連安全補丁都不會出了。

這影響有多大？目前大約 50% 的雲原生環境都在用 NGINX Ingress Controller。也就是說，有一半的 K8s 用戶需要開始認真思考遷移方案了。

好消息是，替代方案不只是「有」，而且是更好的選擇。Kubernetes Gateway API 已經在 2026 年正式 GA（General Availability），達到生產環境可用的成熟度。如果你之前碰過 Kubernetes K8s 入門的基礎，現在正是時候學習 Gateway API 這個下一代標準。

Ingress 和 Gateway API 到底差在哪？

先講結論：Gateway API 不是 Ingress 的小改版，而是從頭設計的全新架構。最核心的差異在於角色分離和協定支援。

Ingress 只能處理 HTTP 和 HTTPS 流量，想要做 TCP、UDP 或 gRPC 路由？抱歉，得靠各家廠商的 annotation 黑魔法。每個 Ingress Controller 的 annotation 都不一樣，寫出來的設定檔基本上無法搬到另一家用。

Gateway API 則原生支援 HTTP、TCP、UDP、gRPC 路由，而且像 Header-based routing（根據 HTTP Header 決定路由）和 traffic splitting（流量分割，做 Canary 部署）都是內建功能，不需要額外的 annotation。

更重要的是，Gateway API 採用角色導向架構，把基礎設施管理員、叢集管理員和應用開發者的職責明確分開。這在大型團隊裡特別有用，不會再出現開發者不小心改壞整個 Ingress 設定的慘劇。

Gateway API 的三大核心資源

Gateway API 的設計圍繞三個關鍵資源，每個資源對應不同的管理角色：

1. GatewayClass — 基礎設施層

GatewayClass 定義了底層使用哪種實作，通常由基礎設施管理員設定。你可以把它想成「選擇要用哪家的 load balancer」。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: production-gateway
spec:
  controllerName: istio.io/gateway-controller
  description: "Production traffic gateway powered by Istio"

目前主流的實作包括 Istio、NGINX Gateway Fabric、Traefik，以及各大雲端供應商的 Load Balancer（GKE、EKS、AKS 都有原生支援）。

2. Gateway — 叢集層

Gateway 資源描述實際的監聽端點，由叢集管理員負責。它決定了「在哪個 port 上聽、接受哪些 namespace 的路由」。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web-gateway
  namespace: infra
spec:
  gatewayClassName: production-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-tls-cert
    - name: http
      protocol: HTTP
      port: 80

注意到了嗎？TLS 設定直接寫在 Gateway 上，不用像 Ingress 一樣每個規則都重複設定。如果你的服務是用微服務架構拆分的，這種集中管理 TLS 的方式會省下很多麻煩。

3. HTTPRoute — 應用層

HTTPRoute 是開發者最常碰到的資源，定義具體的路由規則。這是 Gateway API 最靈活的部分。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-routes
  namespace: app
spec:
  parentRefs:
    - name: web-gateway
      namespace: infra
  hostnames:
    - "api.myapp.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v2/users
          headers:
            - name: X-Api-Version
              value: "2"
      backendRefs:
        - name: users-v2
          port: 8080
          weight: 90
        - name: users-v3
          port: 8080
          weight: 10

上面這個範例同時展示了兩個 Ingress 做不到（或很難做到）的事：Header-based routing 和 traffic splitting。我們根據 X-Api-Version Header 來決定路由，同時把 10% 的流量導向 v3 版本做 Canary 測試。

如果你之前研究過 API Gateway 設計模式，會發現 HTTPRoute 的設計理念和那些模式高度吻合。

從 Ingress 遷移的實戰策略

遷移不用一步到位，建議分三個階段：

階段一：並行運行

在現有的 Ingress 旁邊部署 Gateway API，先用非關鍵服務測試。兩套系統可以同時運行，互不干擾。

# 先安裝 Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml

# 確認 CRDs 安裝成功
kubectl get crd | grep gateway

階段二：逐步切換

把 Ingress 規則一條一條轉成 HTTPRoute。轉換的邏輯其實很直覺：

Ingress 的 host → HTTPRoute 的 hostnames
Ingress 的 path → HTTPRoute 的 matches.path
Ingress 的 backend → HTTPRoute 的 backendRefs
Ingress 的 TLS 設定 → 移到 Gateway 層級統一管理

階段三：下線 Ingress

確認所有流量都走 Gateway API 後，移除舊的 Ingress Controller。記得把相關的 GitHub Actions CI/CD pipeline 裡的 Ingress 部署步驟也一起更新。

特別提醒 Azure AKS 的用戶：微軟承諾 AKS 上的 NGINX Ingress 支援會延續到 2026 年 11 月，但只提供關鍵安全補丁，所以也別拖太久。

超越 HTTP：gRPC 和 TCP 路由

Gateway API 的一個殺手級功能是原生支援 gRPC 路由，這對微服務架構來說太重要了。

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-services
spec:
  parentRefs:
    - name: web-gateway
  hostnames:
    - "grpc.myapp.com"
  rules:
    - matches:
        - method:
            service: myapp.UserService
            method: GetProfile
      backendRefs:
        - name: user-service
          port: 50051

以前要做到這個，你得在 Ingress 上加一堆 NGINX 專屬的 annotation，換成 Traefik 又得全部重寫。Gateway API 把這些都標準化了。

如果你的服務是用 Docker Compose 在本地開發，到了生產環境用 Gateway API 管理，整個流程會順暢很多。

Gateway API 最佳實踐

用了幾個月 Gateway API 之後，這些是我覺得最重要的實踐：

善用 namespace 隔離：Gateway 放在 infra namespace，HTTPRoute 放在各個應用的 namespace。利用 allowedRoutes 控制誰可以掛載路由到你的 Gateway 上。
為每個環境建立獨立的 GatewayClass：dev、staging、production 用不同的 GatewayClass，避免設定互相污染。
先從 HTTPRoute 開始：除非你確定需要 TCPRoute 或 GRPCRoute，否則先把 HTTP 流量搞定就好。Gateway API 的擴展是漸進式的。
監控 Gateway 狀態：Gateway 資源有內建的 status conditions，記得在監控系統中加上對應的告警。
版本化你的路由設定：把所有 Gateway API 的 YAML 檔都放進 Git，搭配 GitOps 工具（ArgoCD 或 Flux）做自動部署。