什么需要 Gateway API?传统 Ingress 的局限性:功能有限:仅支持 HTTP/HTTPS,缺乏对 TCP、UDP、gRPC 等协议的原生支持扩展性差:不同 Ingress Controller 使用不同的注解(annotation),导致配置不兼容表达能力弱:难以实现复杂的流量管理场景(如流量分割、镜像、高级路由匹配)角色分离不清:基础设施团队和应用团队的职责边界模糊Gateway API 的优势:角色导向:明确区分集群操作员、基础设施提供商和应用开发者的职责表达式丰富:支持更复杂的路由规则、流量管理和安全策略协议无关:原生支持 HTTP、HTTPS、TCP、UDP、gRPC、TLS 等多种协议标准化:通过 CRD(Custom Resource Definition)实现跨厂商的一致性可扩展:通过参数化配置支持厂商特定的扩展基础概念核心资源对象Gateway API 定义了一组相互关联的资源对象,每个对象都有明确的职责:GatewayClass (网关类)作用:定义网关的实现类型和配置模板,由基础设施提供商创建和管理。特点:集群级别资源(Cluster-scoped)引用具体的 Gateway Controller 实现一个集群可以有多个 GatewayClass(如 nginx、envoy、istio 等)示例:apiVersion: gateway.networking.k8s.io/v1kind: GatewayClassmetadata:name: nginx-gateway-classspec:controllerName: gateway.networking.k8s.io/nginx-ingress-controller2. Gateway (网关)作用:表示实际的负载均衡器实例,定义监听器(Listeners)和网络端点。特点:命名空间级别资源(Namespace-scoped)引用 GatewayClass 确定实现方式配置监听端口、协议、TLS 证书等由基础设施团队管理示例:apiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata:name: production-gatewaynamespace: web-appspec:gatewayClassName: nginx-gateway-classlisteners:- name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: All- name: httpsport: 443protocol: HTTPStls:mode: TerminatecertificateRefs:- name: tls-secretkind: SecretallowedRoutes:namespaces:from: Same3. HTTPRoute (HTTP 路由)作用:定义如何将 HTTP/HTTPS 流量路由到后端服务,是最常用的路由类型。特点:支持基于路径、主机名、Header、Query 参数的路由规则支持流量权重分配(流量分割)支持请求/响应头修改支持 URL 重写和重定向由应用开发者管理示例:apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: web-app-routenamespace: defaultspec:parentRefs:- name: production-gatewaynamespace: web-apphostnames:- “app.example.com”rules:- matches:- path:type: PathPrefixvalue: /apibackendRefs:- name: api-serviceport: 8080weight: 90- name: api-service-v2port: 8080weight: 10- matches:- path:type: PathPrefixvalue: /backendRefs:- name: web-serviceport: 804. TCPRoute (TCP 路由)作用:路由 TCP 流量到后端服务,适用于数据库、消息队列等场景。示例:apiVersion: gateway.networking.k8s.io/v1alpha2kind: TCPRoutemetadata:name: database-routenamespace: defaultspec:parentRefs:- name: tcp-gatewaynamespace: defaultrules:- backendRefs:- name: backendport: 30005. TLSRoute (TLS 路由)作用:在 TLS 层面路由流量,支持 TLS Passthrough 模式。示例:apiVersion: gateway.networking.k8s.io/v1alpha2kind: TLSRoutemetadata:name: tls-passthrough-routenamespace: defaultspec:parentRefs:- name: tls-gatewayhostnames:- “secure.example.com”rules:- backendRefs:- name: secure-serviceport: 4436. UDPRoute (UDP 路由)作用:路由 UDP 流量,适用于 DNS、游戏服务器等场景。示例:apiVersion: gateway.networking.k8s.io/v1alpha2kind: UDPRoutemetadata:name: dns-routenamespace: defaultspec:parentRefs:- name: udp-gatewayrules:- backendRefs:- name: dns-serviceport: 537. GRPCRoute (gRPC 路由)作用:专门用于 gRPC 流量的路由,支持 gRPC 特有的元数据和方法匹配。示例:apiVersion: gateway.networking.k8s.io/v1kind: GRPCRoutemetadata:name: grpc-service-routenamespace: defaultspec:parentRefs:- name: production-gatewayhostnames:- “grpc.example.com”rules:- matches:- method:service: helloworld.Greetermethod: SayHellobackendRefs:- name: grpc-serviceport: 500518. ReferenceGrant (引用授权)作用:跨命名空间引用的安全机制,允许一个命名空间的资源引用另一个命名空间的资源。示例:apiVersion: gateway.networking.k8s.io/v1beta1kind: ReferenceGrantmetadata:name: allow-gateway-refnamespace: web-appspec:from:- group: gateway.networking.k8s.iokind: HTTPRoutenamespace: defaultto:- group: “”kind: Secretname: tls-secretGateway API vs Ingress 对比特性 Ingress Gateway APIAPI 成熟度 Stable (v1) Graduating to Standard (v1)协议支持 HTTP/HTTPS HTTP, HTTPS, TCP, UDP, gRPC, TLS路由能力 基于路径和主机 路径、主机、Header、Query、方法等流量管理 有限 权重分配、镜像、超时、重试扩展机制 注解(非标准) 参数化配置 CRD角色分离 不明确 清晰的三层模型跨命名空间 不支持 通过 ReferenceGrant 支持TLS 配置 简单 灵活(Terminate/Passthrough)供应商兼容性 差异大 标准化程度高架构原理整体架构Gateway API 遵循 Kubernetes 的标准控制器模式,采用声明式 API 设计:用户/开发者 → Kubernetes API Server → Gateway Controller → Data Plane↓ ↓ ↓ ↓创建资源 存储CRD资源 监听变化并生成配置 代理处理流量工作机制详解资源生命周期创建阶段:用户通过 kubectl apply 创建 Gateway API 资源API Server 验证资源格式并存储到 etcdGateway Controller 通过 Watch 机制检测到新资源Controller 验证资源的语义正确性Controller 将配置转换为数据平面的具体配置Controller 更新资源的 Status 字段,反映配置状态运行阶段:数据平面(如 Envoy)加载最新配置客户端请求到达负载均衡器数据平面根据路由规则匹配请求请求被转发到相应的后端服务响应返回给客户端更新阶段:用户修改资源配置Controller 检测到变更重新计算配置并推送到数据平面数据平面热重载配置(无中断)2. 控制平面与数据平面交互控制平面组件:Gateway Controller:核心控制器,负责资源协调Configuration Generator:将 Gateway API 资源转换为代理特定配置Status Updater:更新资源状态,提供可观测性数据平面组件:Proxy:实际的流量处理引擎(Envoy/Nginx/HAProxy 等)Config Listener:监听配置变化并应用Metrics Exporter:导出监控指标3. 状态反馈机制Gateway API 强调可观测性,每个资源都有详细的 Status 字段:Gateway Status 示例:status:conditions:- type: Acceptedstatus: “True”reason: Acceptedmessage: Gateway successfully accepted- type: Programmedstatus: “True”reason: Programmedmessage: Configuration programmed to data planelisteners:- name: httpattachedRoutes: 5conditions:- type: Readystatus: “True”实践指南环境准备前置要求:Kubernetes 集群 (v1.22)kubectl 命令行工具Helm v3 (可选,用于简化安装)步骤 1: 部署 metallb自建集群没有LB所以需要一个负载下载部署下载应用包wget https://raw.githubusercontent.com/metallb/metallb/v0.15.3/config/manifests/metallb-native.yaml修改镜像地址自行找代理sed -i “s#quay.io#quay.chenby.cn#g” metallb-native.yamlcat metallb-native.yaml | grep imageimage: quay.chenby.cn/metallb/controller:v0.14.5image: quay.chenby.cn/metallb/speaker:v0.14.5执行部署kubectl apply -f metallb-native.yaml可以连接国际网络kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.15.3/config/manifests/metallb-native.yaml查看运行情况cbyDESKTOP-IKRNJQE:~$ kubectl -n metallb-system get allNAME READY STATUS RESTARTS AGEpod/controller-9c6cff498-h7khm 1/1 Running 0 45mpod/speaker-kp5wl 1/1 Running 0 45mNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEservice/metallb-webhook-service ClusterIP 10.68.104.187 443/TCP 45mNAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGEdaemonset.apps/speaker 1 1 1 1 1 kubernetes.io/oslinux 45mNAME READY UP-TO-DATE AVAILABLE AGEdeployment.apps/controller 1/1 1 1 45mNAME DESIRED CURRENT READY AGEreplicaset.apps/controller-9c6cff498 1 1 1 45mcbyDESKTOP-IKRNJQE:~$配置VIP的资源池新版本metallb使用了CRCustom Resources这里我们通过IPAddressPool的CR进行地址池的定义。如果实例中不设置IPAddressPool选择器L2Advertisement那么L2Advertisement默认为该实例所有的IPAddressPool相关联。cat metallb-config-ipaddresspool.yaml EOFapiVersion: metallb.io/v1beta1kind: IPAddressPoolmetadata:name: first-poolnamespace: metallb-systemspec:addresses:192.168.1.15-192.168.1.19EOF进行L2关联地址池的绑定。cat metallb-config-L2Advertisement.yaml EOFapiVersion: metallb.io/v1beta1kind: L2Advertisementmetadata:name: examplenamespace: metallb-systemspec:ipAddressPools:first-poolEOF执行部署kubectl apply -f metallb-config-ipaddresspool.yamlkubectl apply -f metallb-config-L2Advertisement.yaml步骤 2: 安装 Envoy Gateway执行部署https://gateway.envoyproxy.io/docs/install/install-helm/安装网关 API CRD 和 Envoy 网关helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.7.3 -n envoy-gateway-system --create-namespace创建测试应用kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/v1.7.3/quickstart.yaml -n default查看访问地址cbyDESKTOP-IKRNJQE:~$ kubectl get svc -n envoy-gateway-systemNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEenvoy-default-eg-e41e7b31 LoadBalancer 10.68.120.80 192.168.1.15 80:32116/TCP 6senvoy-gateway ClusterIP 10.68.64.83 18000/TCP,18001/TCP,18002/TCP,19001/TCP,9443/TCP 30mcbyDESKTOP-IKRNJQE:~$测试访问cbyDESKTOP-IKRNJQE:~$ curl --verbose --header “Host: www.example.com” http://192.168.1.15/getTrying 192.168.1.15:80…Established connection to 192.168.1.15 (192.168.1.15 port 80) from 172.30.72.41 port 39072using HTTP/1.xGET /get HTTP/1.1Host: www.example.comUser-Agent: curl/8.18.0Accept:/Request completely sent off HTTP/1.1 200 OK content-type: application/json x-content-type-options: nosniff date: Mon, 11 May 2026 13:51:37 GMT content-length: 475{“path”: “/get”,“host”: “www.example.com”,“method”: “GET”,“proto”: “HTTP/1.1”,“headers”: {“Accept”: [“/”],“User-Agent”: [“curl/8.18.0”],“X-Envoy-External-Address”: [“192.168.1.100”],“X-Forwarded-For”: [“192.168.1.100”],“X-Forwarded-Proto”: [“http”],“X-Request-Id”: [“d30d74c9-2c8e-4249-8ca6-ee24156e3317”]},“namespace”: “default”,“ingress”: “”,“service”: “”,“pod”: “backend-869c8646c5-s4426”Connection #0 to host 192.168.1.15:80 left intact}cbyDESKTOP-IKRNJQE:~$其他可选实现:Envoy Gateway: Envoy 官方实现Istio: 服务网格方案Contour: VMware 维护的 Envoy 控制器Kong: Kong Ingress Controller步骤 3: 创建 GatewayClasscat gatewayclass.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: GatewayClassmetadata:name: nginx-gateway-classspec:controllerName: gateway.envoyproxy.io/gatewayclass-controllerEOF应用配置:kubectl apply -f gatewayclass.yamlkubectl get gatewayclasscbyDESKTOP-IKRNJQE:~$ kubectl get gatewayclassgatewayclass.gateway.networking.k8s.io/nginx-gateway-class createdNAME CONTROLLER ACCEPTED AGEeg gateway.envoyproxy.io/gatewayclass-controller True 19mnginx-gateway-class gateway.envoyproxy.io/gatewayclass-controller True 18scbyDESKTOP-IKRNJQE:~$步骤 4: 部署示例应用创建两个简单的后端服务用于测试:cat demo-app.yaml EOFapiVersion: apps/v1kind: Deploymentmetadata:name: web-app-v1spec:replicas: 1selector:matchLabels:app: web-app-v1template:metadata:labels:app: web-app-v1spec:containers:- name: web-app-v1image: registry.cn-hangzhou.aliyuncs.com/chenby/cby:nginx-v1ports:- containerPort: 80apiVersion: apps/v1kind: Deploymentmetadata:name: web-app-v2spec:replicas: 1selector:matchLabels:app: web-app-v2template:metadata:labels:app: web-app-v2spec:containers:- name: web-app-v2image: registry.cn-hangzhou.aliyuncs.com/chenby/cby:nginx-v2ports:- containerPort: 80apiVersion: v1kind: Servicemetadata:labels:app: web-app-v2name: web-app-v2spec:selector:app: web-app-v2ports:port: 80protocol: TCPtargetPort: 80apiVersion: v1kind: Servicemetadata:labels:app: web-app-v1name: web-app-v1spec:selector:app: web-app-v1ports:port: 80protocol: TCPtargetPort: 80EOF同样创建 v2 版本,然后应用:kubectl apply -f demo-app.yaml测试查看cbyDESKTOP-IKRNJQE:~$ kubectl get podNAME READY STATUS RESTARTS AGEbackend-869c8646c5-s4426 1/1 Running 0 20mweb-app-v1-844db9d88f-tjwzz 1/1 Running 0 22sweb-app-v2-dd8d978b8-9stzg 1/1 Running 0 22scbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$ kubectl get svcNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEbackend ClusterIP 10.68.86.118 3000/TCP 21mkubernetes ClusterIP 10.68.0.1 443/TCP 60dweb-app-v1 ClusterIP 10.68.255.182 80/TCP 27sweb-app-v2 ClusterIP 10.68.113.128 80/TCP 27scbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$ curl[[200~10.68.255.182~CcbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$ curl 10.68.255.182Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ cbyDESKTOP-IKRNJQE:~$ curl 10.68.113.128Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 步骤 5: 配置基本 HTTP 路由 首先创建 Gateway:cat gateway.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata:name: production-gatewaynamespace: web-appspec:gatewayClassName: nginx-gateway-classlisteners:- name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: AllEOF创建 HTTPRoute:cat httproute-basic.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: web-app-routenamespace: defaultspec:parentRefs:- name: production-gatewaynamespace: web-apphostnames:- “app.example.com”rules:- matches:- path:type: PathPrefixvalue: /backendRefs:- name: web-app-v1port: 80- name: web-app-v2port: 80EOF应用配置:kubectl create namespace web-appkubectl apply -f gateway.yamlkubectl apply -f httproute-basic.yaml验证kubectl get gateway -n web-appkubectl get httproute -n defaultcbyDESKTOP-IKRNJQE:~$ kubectl get gateway -n web-appNAME CLASS ADDRESS PROGRAMMED AGEproduction-gateway nginx-gateway-class 192.168.1.16 True 13scbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$ kubectl get httproute -n defaultNAME HOSTNAMES AGEbackend [“www.example.com”] 26mweb-app-route [“app.example.com”] 56scbyDESKTOP-IKRNJQE:~$获取 LoadBalancer IP 并测试:curl -H “Host: app.example.com” http://192.168.1.16cbyDESKTOP-IKRNJQE:~$ curl -H “Host: app.example.com” http://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 步骤 6: 配置 TLS 终止 6.1 创建自签名证书(测试用) openssl genrsa -out tls.key 2048 openssl req -new -key tls.key -out tls.csr -subj /CNapp.example.com openssl x509 -req -in tls.csr -signkey tls.key -out tls.crt -days 365kubectl create secret tls app-tls-secret–certtls.crt–keytls.key-n web-apprm tls.key tls.csr tls.crt6.2 更新 Gateway 配置启用 HTTPScat gateway-with-tls.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata:name: production-gatewaynamespace: web-appspec:gatewayClassName: nginx-gateway-classlisteners:- name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: All- name: httpsport: 443protocol: HTTPStls:mode: TerminatecertificateRefs:- name: app-tls-secretkind: Secretgroup: “”allowedRoutes:namespaces:from: AllEOF应用更新:kubectl apply -f gateway-with-tls.yaml测试 HTTPS 访问:curl -k -H “Host: app.example.com” https://192.168.1.16cbyDESKTOP-IKRNJQE:~$ curl -k -H “Host: app.example.com” https://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -k -H Host: app.example.com https://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -k -H Host: app.example.com https://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -k -H Host: app.example.com https://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -k -H Host: app.example.com https://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 步骤 7: 配置流量分割(金丝雀发布) 创建将 90% 流量发送到 v1,10% 流量发送到 v2 的路由:cat httproute-canary.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: web-app-canary-routenamespace: defaultspec:parentRefs:- name: production-gatewaynamespace: web-apphostnames:- “app.example.com”rules:- matches:- path:type: PathPrefixvalue: /backendRefs:- name: web-app-v1port: 80weight: 90- name: web-app-v2port: 80weight: 10EOF应用配置:kubectl delete -f httproute-basic.yamlkubectl apply -f httproute-canary.yamlcbyDESKTOP-IKRNJQE:~$ kubectl get HTTPRouteNAMESPACE NAME HOSTNAMES AGEdefault backend [“www.example.com”] 45mdefault web-app-canary-route [“app.example.com”] 104scbyDESKTOP-IKRNJQE:~$测试流量分割:for i in {1…20}; docurl -s -H “Host: app.example.com” http://192.168.1.16donecbyDESKTOP-IKRNJQE:~$ for i in {1…20}; docurl -s -H “Host: app.example.com” http://192.168.1.16doneHello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 步骤 8: 高级路由配置 8.1 基于 Header 的路由 cat httproute-header.yaml EOF apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: header-based-route namespace: default spec: parentRefs: - name: production-gateway namespace: web-app hostnames: - app.example.com rules: - matches: - headers: - name: x-version value: v2 backendRefs: - name: web-app-v2 port: 80 - matches: - path: type: PathPrefix value: / backendRefs: - name: web-app-v1 port: 80 EOF 测试:kubectl delete -f httproute-canary.yamlkubectl apply -f httproute-header.yaml不带 Header,访问 v1curl -H “Host: app.example.com” http://192.168.1.16带 Header,访问 v2curl -H “Host: app.example.com” -H “x-version: v2” http://192.168.1.16cbyDESKTOP-IKRNJQE:~$ curl -H “Host: app.example.com” http://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com -H x-version: v2 http://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 8.2 URL 重写 cat httproute-rewrite.yaml EOF apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: rewrite-route namespace: default spec: parentRefs: - name: production-gateway namespace: web-app hostnames: - app.example.com rules: - matches: - path: type: PathPrefix value: /api/v1 filters: - type: URLRewrite urlRewrite: path: type: ReplacePrefixMatch replacePrefixMatch: / backendRefs: - name: web-app-v1 port: 80 - matches: - path: type: PathPrefix value: /api/v2 filters: - type: URLRewrite urlRewrite: path: type: ReplacePrefixMatch replacePrefixMatch: / backendRefs: - name: web-app-v2 port: 80 EOF 测试使用kubectl delete -f httproute-header.yamlkubectl apply -f httproute-rewrite.yamlcurl -H “Host: app.example.com” http://192.168.1.16/api/v1curl -H “Host: app.example.com” http://192.168.1.16/api/v2cbyDESKTOP-IKRNJQE:~$ curl -H “Host: app.example.com” http://192.168.1.16/api/v1Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16/api/v2Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 8.3 请求/响应头修改 cat httproute-modify.yaml EOF apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: header-modify-route namespace: default spec: parentRefs: - name: production-gateway namespace: web-app hostnames: - app.example.com rules: - matches: - path: type: PathPrefix value: / filters: - type: RequestHeaderModifier requestHeaderModifier: add: - name: X-Forwarded-Gateway value: nginx-gateway set: - name: X-Custom-Header value: custom-value - type: ResponseHeaderModifier responseHeaderModifier: add: - name: X-Powered-By value: Gateway-API backendRefs: - name: web-app-v1 port: 80 EOF kubectl delete -f httproute-rewrite.yaml kubectl apply -f httproute-modify.yamlcurl -v -H “Host: app.example.com” http://192.168.1.16/cbyDESKTOP-IKRNJQE:~$ curl -v -H “Host: app.example.com” http://192.168.1.16/Trying 192.168.1.16:80…Established connection to 192.168.1.16 (192.168.1.16 port 80) from 172.30.72.41 port 46798using HTTP/1.xGET / HTTP/1.1Host: app.example.comUser-Agent: curl/8.18.0Accept:/Request completely sent off HTTP/1.1 200 OK server: nginx/1.29.8 date: Mon, 11 May 2026 14:54:24 GMT content-type: text/html content-length: 128 last-modified: Mon, 11 May 2026 14:02:13 GMT etag: “6a01e165-80” accept-ranges: bytes x-powered-by: Gateway-APIHello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市* Connection #0 to host 192.168.1.16:80 left intact cbyDESKTOP-IKRNJQE:~$ 最佳实践 1. 安全管理 1.1 使用 RBAC 限制权限 为应用团队创建受限角色,只允许管理 Route 资源:apiVersion: rbac.authorization.k8s.io/v1kind: Rolemetadata:name: gateway-route-managernamespace: defaultrules:apiGroups: [“gateway.networking.k8s.io”]resources: [“httproutes”, “grpcroutes”]verbs: [“get”, “list”, “watch”, “create”, “update”, “patch”]1.2 使用 ReferenceGrant 控制跨命名空间访问apiVersion: gateway.networking.k8s.io/v1beta1kind: ReferenceGrantmetadata:name: allow-tls-refnamespace: cert-managerspec:from:group: gateway.networking.k8s.iokind: Gatewaynamespace: web-appto:group: “”kind: Secretname: wildcard-tls-cert1.3 TLS 最佳实践使用通配符证书减少证书管理复杂度定期轮换证书,建议使用 cert-manager 自动化优先使用 TLS Terminate 模式强制 HTTPS,配置 HTTP 到 HTTPS 重定向性能优化2.1 合理配置监听器限制允许的路由来源,减少配置复杂度:spec:listeners:- name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: Selectorselector:matchLabels:allow-gateway-access: “true”2.2 避免过度复杂的路由规则合并相似的路由规则,减少配置数量使用最具体的匹配条件优先,提高匹配效率避免过多的 Header/Query 匹配,影响性能3. 可靠性保障3.1 渐进式发布策略金丝雀发布流程:部署新版本服务(v2)配置 5% 流量到 v2监控错误率和延迟逐步增加流量比例(10% → 25% → 50% → 100%)确认稳定后,移除旧版本阶段 1: 5% 流量backendRefs:name: web-app-v1weight: 95name: web-app-v2weight: 5阶段 2: 25% 流量backendRefs:name: web-app-v1weight: 75name: web-app-v2weight: 25阶段 3: 100% 流量backendRefs:name: web-app-v2weight: 1003.2 蓝绿部署通过快速切换权重实现蓝绿部署:初始状态: 100% 蓝色环境backendRefs:name: blue-serviceweight: 100name: green-serviceweight: 0切换时: 快速切换到绿色环境backendRefs:name: blue-serviceweight: 0name: green-serviceweight: 100多租户隔离4.1 命名空间隔离策略spec:listeners:name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: Selectorselector:matchLabels:environment: production调试和故障排查5.1 常见问题诊断清单问题 1: Gateway 状态为 “Not Accepted”检查步骤:1. 检查 GatewayClass 是否存在且有效kubectl get gatewayclass2. 检查 Controller 是否运行kubectl get pods -n3. 查看 Gateway 事件kubectl describe gateway -n4. 检查控制器日志kubectl logs -n -l app问题 2: HTTPRoute 未被接受检查步骤:1. 验证 parentRefs 是否正确kubectl get httproute -o yaml2. 检查 Gateway 是否允许该命名空间的路由kubectl describe gateway -n3. 验证后端服务是否存在kubectl get svc4. 检查 ReferenceGrant (如果跨命名空间)kubectl get referencegrant -A问题 3: 流量未正确路由检查步骤:1. 验证路由规则匹配条件kubectl describe httproute2. 测试后端服务直接访问kubectl run test --rm -i --tty --imagecurlimages/curl –curl http://..svc.cluster.local3. 检查 Gateway 外部 IPkubectl get gateway -o jsonpath‘{.status.addresses}’4. 使用详细输出测试curl -v -H “Host: ” http://6. 生产环境建议6.1 高可用架构部署多个 Controller 副本实现控制器高可用使用多个 Gateway 实例分散负载配置跨区域部署提高灾难恢复能力spec:replicas: 3strategy:type: RollingUpdaterollingUpdate:maxSurge: 1maxUnavailable: 06.2 备份和恢复定期备份 Gateway API 资源配置使用 GitOps 工具(如 ArgoCD、Flux)管理配置建立配置变更审批流程备份所有 Gateway API 资源kubectl get gatewayclass,gateway,httproute,tcproute,referencegrant -A -o yaml gateway-backup.yaml6.3 容量规划关键监控指标:每秒请求数 (RPS)平均/ P95/P99 延迟错误率 (4xx, 5xx)活跃连接数带宽使用率6.4 版本升级策略先在测试环境验证新版本阅读发行说明,了解破坏性变更灰度升级,先升级部分节点保留回滚方案7. 常见应用场景场景 1: 多域名托管apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: multi-domain-routespec:parentRefs:- name: production-gatewayhostnames:- “app1.example.com”- “app2.example.com”- “app3.example.com”rules:- matches:- path:type: PathPrefixvalue: /backendRefs:- name: shared-backendport: 80场景 2: API 网关apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: api-gateway-routespec:parentRefs:- name: production-gatewayhostnames:- “api.example.com”rules:- matches:- path:type: PathPrefixvalue: /usersbackendRefs:- name: user-serviceport: 8080- matches:- path:type: PathPrefixvalue: /ordersbackendRefs:- name: order-serviceport: 8080- matches:- path:type: PathPrefixvalue: /paymentsbackendRefs:- name: payment-serviceport: 8080场景 3: A/B 测试apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: ab-test-routespec:parentRefs:- name: production-gatewayhostnames:- “app.example.com”rules:- matches:- path:type: PathPrefixvalue: /backendRefs:- name: variant-aport: 80weight: 50- name: variant-bport: 80weight: 50常见问题与故障排查FAQQ1: Gateway API 和 Ingress 可以共存吗?A: 可以。它们使用不同的资源类型,可以同时在集群中运行。建议逐步迁移,先在新服务中使用 Gateway API。Q2: 如何选择 Gateway Controller 实现?A: 考虑因素:功能需求:是否需要 gRPC、TCP 等高级功能性能要求:吞吐量、延迟指标生态系统:与现有工具链的集成社区活跃度:维护频率、问题响应速度企业支持:是否需要商业支持推荐选择:通用场景: Envoy Gateway、NGINX Gateway Fabric服务网格: Istio高性能: Envoy Gateway简单易用: ContourQ3: Gateway API 的性能如何?A: Gateway API 本身是控制平面,性能取决于数据平面实现(Envoy/Nginx 等)、配置复杂度和硬件资源。现代实现(如 Envoy)可以达到数十万 QPS,延迟在毫秒级。Q4: 如何处理 WebSocket 连接?A: HTTPRoute 天然支持 WebSocket,无需特殊配置。确保后端服务正确处理 Upgrade 头即可。Q5: 可以实现速率限制吗?A: Gateway API v1 标准不直接支持速率限制,但可以通过以下方式实现:Controller 特定扩展(如 Envoy Gateway 的 RateLimitFilter)在服务网格层实现(Istio)使用外部速率限制服务Q6: 如何迁移现有的 Ingress 配置?A: 迁移步骤:分析现有 Ingress 资源映射 Ingress 规则到 HTTPRoute创建对应的 Gateway 资源测试新配置逐步切换流量删除旧 Ingress 资源可以使用官方工具 ingress2gateway 辅助转换:kubectl get ingress -A -o yaml | ingress2gateway -f -Q7: Gateway API 支持哪些 Kubernetes 版本?A: Gateway API v1 需要 Kubernetes 1.22,推荐使用最新的稳定版 Kubernetes 以获得最佳支持。Q8: 如何实现灰度发布的自动化?A: 结合以下工具:Argo Rollouts:渐进式交付Flagger:自动化的金丝雀分析自定义控制器:根据监控指标自动调整权重总结
Kubernetes Gateway API 完全指南
什么需要 Gateway API?传统 Ingress 的局限性:功能有限:仅支持 HTTP/HTTPS,缺乏对 TCP、UDP、gRPC 等协议的原生支持扩展性差:不同 Ingress Controller 使用不同的注解(annotation),导致配置不兼容表达能力弱:难以实现复杂的流量管理场景(如流量分割、镜像、高级路由匹配)角色分离不清:基础设施团队和应用团队的职责边界模糊Gateway API 的优势:角色导向:明确区分集群操作员、基础设施提供商和应用开发者的职责表达式丰富:支持更复杂的路由规则、流量管理和安全策略协议无关:原生支持 HTTP、HTTPS、TCP、UDP、gRPC、TLS 等多种协议标准化:通过 CRD(Custom Resource Definition)实现跨厂商的一致性可扩展:通过参数化配置支持厂商特定的扩展基础概念核心资源对象Gateway API 定义了一组相互关联的资源对象,每个对象都有明确的职责:GatewayClass (网关类)作用:定义网关的实现类型和配置模板,由基础设施提供商创建和管理。特点:集群级别资源(Cluster-scoped)引用具体的 Gateway Controller 实现一个集群可以有多个 GatewayClass(如 nginx、envoy、istio 等)示例:apiVersion: gateway.networking.k8s.io/v1kind: GatewayClassmetadata:name: nginx-gateway-classspec:controllerName: gateway.networking.k8s.io/nginx-ingress-controller2. Gateway (网关)作用:表示实际的负载均衡器实例,定义监听器(Listeners)和网络端点。特点:命名空间级别资源(Namespace-scoped)引用 GatewayClass 确定实现方式配置监听端口、协议、TLS 证书等由基础设施团队管理示例:apiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata:name: production-gatewaynamespace: web-appspec:gatewayClassName: nginx-gateway-classlisteners:- name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: All- name: httpsport: 443protocol: HTTPStls:mode: TerminatecertificateRefs:- name: tls-secretkind: SecretallowedRoutes:namespaces:from: Same3. HTTPRoute (HTTP 路由)作用:定义如何将 HTTP/HTTPS 流量路由到后端服务,是最常用的路由类型。特点:支持基于路径、主机名、Header、Query 参数的路由规则支持流量权重分配(流量分割)支持请求/响应头修改支持 URL 重写和重定向由应用开发者管理示例:apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: web-app-routenamespace: defaultspec:parentRefs:- name: production-gatewaynamespace: web-apphostnames:- “app.example.com”rules:- matches:- path:type: PathPrefixvalue: /apibackendRefs:- name: api-serviceport: 8080weight: 90- name: api-service-v2port: 8080weight: 10- matches:- path:type: PathPrefixvalue: /backendRefs:- name: web-serviceport: 804. TCPRoute (TCP 路由)作用:路由 TCP 流量到后端服务,适用于数据库、消息队列等场景。示例:apiVersion: gateway.networking.k8s.io/v1alpha2kind: TCPRoutemetadata:name: database-routenamespace: defaultspec:parentRefs:- name: tcp-gatewaynamespace: defaultrules:- backendRefs:- name: backendport: 30005. TLSRoute (TLS 路由)作用:在 TLS 层面路由流量,支持 TLS Passthrough 模式。示例:apiVersion: gateway.networking.k8s.io/v1alpha2kind: TLSRoutemetadata:name: tls-passthrough-routenamespace: defaultspec:parentRefs:- name: tls-gatewayhostnames:- “secure.example.com”rules:- backendRefs:- name: secure-serviceport: 4436. UDPRoute (UDP 路由)作用:路由 UDP 流量,适用于 DNS、游戏服务器等场景。示例:apiVersion: gateway.networking.k8s.io/v1alpha2kind: UDPRoutemetadata:name: dns-routenamespace: defaultspec:parentRefs:- name: udp-gatewayrules:- backendRefs:- name: dns-serviceport: 537. GRPCRoute (gRPC 路由)作用:专门用于 gRPC 流量的路由,支持 gRPC 特有的元数据和方法匹配。示例:apiVersion: gateway.networking.k8s.io/v1kind: GRPCRoutemetadata:name: grpc-service-routenamespace: defaultspec:parentRefs:- name: production-gatewayhostnames:- “grpc.example.com”rules:- matches:- method:service: helloworld.Greetermethod: SayHellobackendRefs:- name: grpc-serviceport: 500518. ReferenceGrant (引用授权)作用:跨命名空间引用的安全机制,允许一个命名空间的资源引用另一个命名空间的资源。示例:apiVersion: gateway.networking.k8s.io/v1beta1kind: ReferenceGrantmetadata:name: allow-gateway-refnamespace: web-appspec:from:- group: gateway.networking.k8s.iokind: HTTPRoutenamespace: defaultto:- group: “”kind: Secretname: tls-secretGateway API vs Ingress 对比特性 Ingress Gateway APIAPI 成熟度 Stable (v1) Graduating to Standard (v1)协议支持 HTTP/HTTPS HTTP, HTTPS, TCP, UDP, gRPC, TLS路由能力 基于路径和主机 路径、主机、Header、Query、方法等流量管理 有限 权重分配、镜像、超时、重试扩展机制 注解(非标准) 参数化配置 CRD角色分离 不明确 清晰的三层模型跨命名空间 不支持 通过 ReferenceGrant 支持TLS 配置 简单 灵活(Terminate/Passthrough)供应商兼容性 差异大 标准化程度高架构原理整体架构Gateway API 遵循 Kubernetes 的标准控制器模式,采用声明式 API 设计:用户/开发者 → Kubernetes API Server → Gateway Controller → Data Plane↓ ↓ ↓ ↓创建资源 存储CRD资源 监听变化并生成配置 代理处理流量工作机制详解资源生命周期创建阶段:用户通过 kubectl apply 创建 Gateway API 资源API Server 验证资源格式并存储到 etcdGateway Controller 通过 Watch 机制检测到新资源Controller 验证资源的语义正确性Controller 将配置转换为数据平面的具体配置Controller 更新资源的 Status 字段,反映配置状态运行阶段:数据平面(如 Envoy)加载最新配置客户端请求到达负载均衡器数据平面根据路由规则匹配请求请求被转发到相应的后端服务响应返回给客户端更新阶段:用户修改资源配置Controller 检测到变更重新计算配置并推送到数据平面数据平面热重载配置(无中断)2. 控制平面与数据平面交互控制平面组件:Gateway Controller:核心控制器,负责资源协调Configuration Generator:将 Gateway API 资源转换为代理特定配置Status Updater:更新资源状态,提供可观测性数据平面组件:Proxy:实际的流量处理引擎(Envoy/Nginx/HAProxy 等)Config Listener:监听配置变化并应用Metrics Exporter:导出监控指标3. 状态反馈机制Gateway API 强调可观测性,每个资源都有详细的 Status 字段:Gateway Status 示例:status:conditions:- type: Acceptedstatus: “True”reason: Acceptedmessage: Gateway successfully accepted- type: Programmedstatus: “True”reason: Programmedmessage: Configuration programmed to data planelisteners:- name: httpattachedRoutes: 5conditions:- type: Readystatus: “True”实践指南环境准备前置要求:Kubernetes 集群 (v1.22)kubectl 命令行工具Helm v3 (可选,用于简化安装)步骤 1: 部署 metallb自建集群没有LB所以需要一个负载下载部署下载应用包wget https://raw.githubusercontent.com/metallb/metallb/v0.15.3/config/manifests/metallb-native.yaml修改镜像地址自行找代理sed -i “s#quay.io#quay.chenby.cn#g” metallb-native.yamlcat metallb-native.yaml | grep imageimage: quay.chenby.cn/metallb/controller:v0.14.5image: quay.chenby.cn/metallb/speaker:v0.14.5执行部署kubectl apply -f metallb-native.yaml可以连接国际网络kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.15.3/config/manifests/metallb-native.yaml查看运行情况cbyDESKTOP-IKRNJQE:~$ kubectl -n metallb-system get allNAME READY STATUS RESTARTS AGEpod/controller-9c6cff498-h7khm 1/1 Running 0 45mpod/speaker-kp5wl 1/1 Running 0 45mNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEservice/metallb-webhook-service ClusterIP 10.68.104.187 443/TCP 45mNAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGEdaemonset.apps/speaker 1 1 1 1 1 kubernetes.io/oslinux 45mNAME READY UP-TO-DATE AVAILABLE AGEdeployment.apps/controller 1/1 1 1 45mNAME DESIRED CURRENT READY AGEreplicaset.apps/controller-9c6cff498 1 1 1 45mcbyDESKTOP-IKRNJQE:~$配置VIP的资源池新版本metallb使用了CRCustom Resources这里我们通过IPAddressPool的CR进行地址池的定义。如果实例中不设置IPAddressPool选择器L2Advertisement那么L2Advertisement默认为该实例所有的IPAddressPool相关联。cat metallb-config-ipaddresspool.yaml EOFapiVersion: metallb.io/v1beta1kind: IPAddressPoolmetadata:name: first-poolnamespace: metallb-systemspec:addresses:192.168.1.15-192.168.1.19EOF进行L2关联地址池的绑定。cat metallb-config-L2Advertisement.yaml EOFapiVersion: metallb.io/v1beta1kind: L2Advertisementmetadata:name: examplenamespace: metallb-systemspec:ipAddressPools:first-poolEOF执行部署kubectl apply -f metallb-config-ipaddresspool.yamlkubectl apply -f metallb-config-L2Advertisement.yaml步骤 2: 安装 Envoy Gateway执行部署https://gateway.envoyproxy.io/docs/install/install-helm/安装网关 API CRD 和 Envoy 网关helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.7.3 -n envoy-gateway-system --create-namespace创建测试应用kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/v1.7.3/quickstart.yaml -n default查看访问地址cbyDESKTOP-IKRNJQE:~$ kubectl get svc -n envoy-gateway-systemNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEenvoy-default-eg-e41e7b31 LoadBalancer 10.68.120.80 192.168.1.15 80:32116/TCP 6senvoy-gateway ClusterIP 10.68.64.83 18000/TCP,18001/TCP,18002/TCP,19001/TCP,9443/TCP 30mcbyDESKTOP-IKRNJQE:~$测试访问cbyDESKTOP-IKRNJQE:~$ curl --verbose --header “Host: www.example.com” http://192.168.1.15/getTrying 192.168.1.15:80…Established connection to 192.168.1.15 (192.168.1.15 port 80) from 172.30.72.41 port 39072using HTTP/1.xGET /get HTTP/1.1Host: www.example.comUser-Agent: curl/8.18.0Accept:/Request completely sent off HTTP/1.1 200 OK content-type: application/json x-content-type-options: nosniff date: Mon, 11 May 2026 13:51:37 GMT content-length: 475{“path”: “/get”,“host”: “www.example.com”,“method”: “GET”,“proto”: “HTTP/1.1”,“headers”: {“Accept”: [“/”],“User-Agent”: [“curl/8.18.0”],“X-Envoy-External-Address”: [“192.168.1.100”],“X-Forwarded-For”: [“192.168.1.100”],“X-Forwarded-Proto”: [“http”],“X-Request-Id”: [“d30d74c9-2c8e-4249-8ca6-ee24156e3317”]},“namespace”: “default”,“ingress”: “”,“service”: “”,“pod”: “backend-869c8646c5-s4426”Connection #0 to host 192.168.1.15:80 left intact}cbyDESKTOP-IKRNJQE:~$其他可选实现:Envoy Gateway: Envoy 官方实现Istio: 服务网格方案Contour: VMware 维护的 Envoy 控制器Kong: Kong Ingress Controller步骤 3: 创建 GatewayClasscat gatewayclass.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: GatewayClassmetadata:name: nginx-gateway-classspec:controllerName: gateway.envoyproxy.io/gatewayclass-controllerEOF应用配置:kubectl apply -f gatewayclass.yamlkubectl get gatewayclasscbyDESKTOP-IKRNJQE:~$ kubectl get gatewayclassgatewayclass.gateway.networking.k8s.io/nginx-gateway-class createdNAME CONTROLLER ACCEPTED AGEeg gateway.envoyproxy.io/gatewayclass-controller True 19mnginx-gateway-class gateway.envoyproxy.io/gatewayclass-controller True 18scbyDESKTOP-IKRNJQE:~$步骤 4: 部署示例应用创建两个简单的后端服务用于测试:cat demo-app.yaml EOFapiVersion: apps/v1kind: Deploymentmetadata:name: web-app-v1spec:replicas: 1selector:matchLabels:app: web-app-v1template:metadata:labels:app: web-app-v1spec:containers:- name: web-app-v1image: registry.cn-hangzhou.aliyuncs.com/chenby/cby:nginx-v1ports:- containerPort: 80apiVersion: apps/v1kind: Deploymentmetadata:name: web-app-v2spec:replicas: 1selector:matchLabels:app: web-app-v2template:metadata:labels:app: web-app-v2spec:containers:- name: web-app-v2image: registry.cn-hangzhou.aliyuncs.com/chenby/cby:nginx-v2ports:- containerPort: 80apiVersion: v1kind: Servicemetadata:labels:app: web-app-v2name: web-app-v2spec:selector:app: web-app-v2ports:port: 80protocol: TCPtargetPort: 80apiVersion: v1kind: Servicemetadata:labels:app: web-app-v1name: web-app-v1spec:selector:app: web-app-v1ports:port: 80protocol: TCPtargetPort: 80EOF同样创建 v2 版本,然后应用:kubectl apply -f demo-app.yaml测试查看cbyDESKTOP-IKRNJQE:~$ kubectl get podNAME READY STATUS RESTARTS AGEbackend-869c8646c5-s4426 1/1 Running 0 20mweb-app-v1-844db9d88f-tjwzz 1/1 Running 0 22sweb-app-v2-dd8d978b8-9stzg 1/1 Running 0 22scbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$ kubectl get svcNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEbackend ClusterIP 10.68.86.118 3000/TCP 21mkubernetes ClusterIP 10.68.0.1 443/TCP 60dweb-app-v1 ClusterIP 10.68.255.182 80/TCP 27sweb-app-v2 ClusterIP 10.68.113.128 80/TCP 27scbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$ curl[[200~10.68.255.182~CcbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$ curl 10.68.255.182Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ cbyDESKTOP-IKRNJQE:~$ curl 10.68.113.128Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 步骤 5: 配置基本 HTTP 路由 首先创建 Gateway:cat gateway.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata:name: production-gatewaynamespace: web-appspec:gatewayClassName: nginx-gateway-classlisteners:- name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: AllEOF创建 HTTPRoute:cat httproute-basic.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: web-app-routenamespace: defaultspec:parentRefs:- name: production-gatewaynamespace: web-apphostnames:- “app.example.com”rules:- matches:- path:type: PathPrefixvalue: /backendRefs:- name: web-app-v1port: 80- name: web-app-v2port: 80EOF应用配置:kubectl create namespace web-appkubectl apply -f gateway.yamlkubectl apply -f httproute-basic.yaml验证kubectl get gateway -n web-appkubectl get httproute -n defaultcbyDESKTOP-IKRNJQE:~$ kubectl get gateway -n web-appNAME CLASS ADDRESS PROGRAMMED AGEproduction-gateway nginx-gateway-class 192.168.1.16 True 13scbyDESKTOP-IKRNJQE:~$cbyDESKTOP-IKRNJQE:~$ kubectl get httproute -n defaultNAME HOSTNAMES AGEbackend [“www.example.com”] 26mweb-app-route [“app.example.com”] 56scbyDESKTOP-IKRNJQE:~$获取 LoadBalancer IP 并测试:curl -H “Host: app.example.com” http://192.168.1.16cbyDESKTOP-IKRNJQE:~$ curl -H “Host: app.example.com” http://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 步骤 6: 配置 TLS 终止 6.1 创建自签名证书(测试用) openssl genrsa -out tls.key 2048 openssl req -new -key tls.key -out tls.csr -subj /CNapp.example.com openssl x509 -req -in tls.csr -signkey tls.key -out tls.crt -days 365kubectl create secret tls app-tls-secret–certtls.crt–keytls.key-n web-apprm tls.key tls.csr tls.crt6.2 更新 Gateway 配置启用 HTTPScat gateway-with-tls.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata:name: production-gatewaynamespace: web-appspec:gatewayClassName: nginx-gateway-classlisteners:- name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: All- name: httpsport: 443protocol: HTTPStls:mode: TerminatecertificateRefs:- name: app-tls-secretkind: Secretgroup: “”allowedRoutes:namespaces:from: AllEOF应用更新:kubectl apply -f gateway-with-tls.yaml测试 HTTPS 访问:curl -k -H “Host: app.example.com” https://192.168.1.16cbyDESKTOP-IKRNJQE:~$ curl -k -H “Host: app.example.com” https://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -k -H Host: app.example.com https://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -k -H Host: app.example.com https://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -k -H Host: app.example.com https://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -k -H Host: app.example.com https://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 步骤 7: 配置流量分割(金丝雀发布) 创建将 90% 流量发送到 v1,10% 流量发送到 v2 的路由:cat httproute-canary.yaml EOFapiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: web-app-canary-routenamespace: defaultspec:parentRefs:- name: production-gatewaynamespace: web-apphostnames:- “app.example.com”rules:- matches:- path:type: PathPrefixvalue: /backendRefs:- name: web-app-v1port: 80weight: 90- name: web-app-v2port: 80weight: 10EOF应用配置:kubectl delete -f httproute-basic.yamlkubectl apply -f httproute-canary.yamlcbyDESKTOP-IKRNJQE:~$ kubectl get HTTPRouteNAMESPACE NAME HOSTNAMES AGEdefault backend [“www.example.com”] 45mdefault web-app-canary-route [“app.example.com”] 104scbyDESKTOP-IKRNJQE:~$测试流量分割:for i in {1…20}; docurl -s -H “Host: app.example.com” http://192.168.1.16donecbyDESKTOP-IKRNJQE:~$ for i in {1…20}; docurl -s -H “Host: app.example.com” http://192.168.1.16doneHello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 步骤 8: 高级路由配置 8.1 基于 Header 的路由 cat httproute-header.yaml EOF apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: header-based-route namespace: default spec: parentRefs: - name: production-gateway namespace: web-app hostnames: - app.example.com rules: - matches: - headers: - name: x-version value: v2 backendRefs: - name: web-app-v2 port: 80 - matches: - path: type: PathPrefix value: / backendRefs: - name: web-app-v1 port: 80 EOF 测试:kubectl delete -f httproute-canary.yamlkubectl apply -f httproute-header.yaml不带 Header,访问 v1curl -H “Host: app.example.com” http://192.168.1.16带 Header,访问 v2curl -H “Host: app.example.com” -H “x-version: v2” http://192.168.1.16cbyDESKTOP-IKRNJQE:~$ curl -H “Host: app.example.com” http://192.168.1.16Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com -H x-version: v2 http://192.168.1.16Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 8.2 URL 重写 cat httproute-rewrite.yaml EOF apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: rewrite-route namespace: default spec: parentRefs: - name: production-gateway namespace: web-app hostnames: - app.example.com rules: - matches: - path: type: PathPrefix value: /api/v1 filters: - type: URLRewrite urlRewrite: path: type: ReplacePrefixMatch replacePrefixMatch: / backendRefs: - name: web-app-v1 port: 80 - matches: - path: type: PathPrefix value: /api/v2 filters: - type: URLRewrite urlRewrite: path: type: ReplacePrefixMatch replacePrefixMatch: / backendRefs: - name: web-app-v2 port: 80 EOF 测试使用kubectl delete -f httproute-header.yamlkubectl apply -f httproute-rewrite.yamlcurl -H “Host: app.example.com” http://192.168.1.16/api/v1curl -H “Host: app.example.com” http://192.168.1.16/api/v2cbyDESKTOP-IKRNJQE:~$ curl -H “Host: app.example.com” http://192.168.1.16/api/v1Hello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ curl -H Host: app.example.com http://192.168.1.16/api/v2Hello V2时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市cbyDESKTOP-IKRNJQE:~$ 8.3 请求/响应头修改 cat httproute-modify.yaml EOF apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: header-modify-route namespace: default spec: parentRefs: - name: production-gateway namespace: web-app hostnames: - app.example.com rules: - matches: - path: type: PathPrefix value: / filters: - type: RequestHeaderModifier requestHeaderModifier: add: - name: X-Forwarded-Gateway value: nginx-gateway set: - name: X-Custom-Header value: custom-value - type: ResponseHeaderModifier responseHeaderModifier: add: - name: X-Powered-By value: Gateway-API backendRefs: - name: web-app-v1 port: 80 EOF kubectl delete -f httproute-rewrite.yaml kubectl apply -f httproute-modify.yamlcurl -v -H “Host: app.example.com” http://192.168.1.16/cbyDESKTOP-IKRNJQE:~$ curl -v -H “Host: app.example.com” http://192.168.1.16/Trying 192.168.1.16:80…Established connection to 192.168.1.16 (192.168.1.16 port 80) from 172.30.72.41 port 46798using HTTP/1.xGET / HTTP/1.1Host: app.example.comUser-Agent: curl/8.18.0Accept:/Request completely sent off HTTP/1.1 200 OK server: nginx/1.29.8 date: Mon, 11 May 2026 14:54:24 GMT content-type: text/html content-length: 128 last-modified: Mon, 11 May 2026 14:02:13 GMT etag: “6a01e165-80” accept-ranges: bytes x-powered-by: Gateway-APIHello V1时间2026-05-11 星期一地点内蒙古自治区 呼和浩特市* Connection #0 to host 192.168.1.16:80 left intact cbyDESKTOP-IKRNJQE:~$ 最佳实践 1. 安全管理 1.1 使用 RBAC 限制权限 为应用团队创建受限角色,只允许管理 Route 资源:apiVersion: rbac.authorization.k8s.io/v1kind: Rolemetadata:name: gateway-route-managernamespace: defaultrules:apiGroups: [“gateway.networking.k8s.io”]resources: [“httproutes”, “grpcroutes”]verbs: [“get”, “list”, “watch”, “create”, “update”, “patch”]1.2 使用 ReferenceGrant 控制跨命名空间访问apiVersion: gateway.networking.k8s.io/v1beta1kind: ReferenceGrantmetadata:name: allow-tls-refnamespace: cert-managerspec:from:group: gateway.networking.k8s.iokind: Gatewaynamespace: web-appto:group: “”kind: Secretname: wildcard-tls-cert1.3 TLS 最佳实践使用通配符证书减少证书管理复杂度定期轮换证书,建议使用 cert-manager 自动化优先使用 TLS Terminate 模式强制 HTTPS,配置 HTTP 到 HTTPS 重定向性能优化2.1 合理配置监听器限制允许的路由来源,减少配置复杂度:spec:listeners:- name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: Selectorselector:matchLabels:allow-gateway-access: “true”2.2 避免过度复杂的路由规则合并相似的路由规则,减少配置数量使用最具体的匹配条件优先,提高匹配效率避免过多的 Header/Query 匹配,影响性能3. 可靠性保障3.1 渐进式发布策略金丝雀发布流程:部署新版本服务(v2)配置 5% 流量到 v2监控错误率和延迟逐步增加流量比例(10% → 25% → 50% → 100%)确认稳定后,移除旧版本阶段 1: 5% 流量backendRefs:name: web-app-v1weight: 95name: web-app-v2weight: 5阶段 2: 25% 流量backendRefs:name: web-app-v1weight: 75name: web-app-v2weight: 25阶段 3: 100% 流量backendRefs:name: web-app-v2weight: 1003.2 蓝绿部署通过快速切换权重实现蓝绿部署:初始状态: 100% 蓝色环境backendRefs:name: blue-serviceweight: 100name: green-serviceweight: 0切换时: 快速切换到绿色环境backendRefs:name: blue-serviceweight: 0name: green-serviceweight: 100多租户隔离4.1 命名空间隔离策略spec:listeners:name: httpport: 80protocol: HTTPallowedRoutes:namespaces:from: Selectorselector:matchLabels:environment: production调试和故障排查5.1 常见问题诊断清单问题 1: Gateway 状态为 “Not Accepted”检查步骤:1. 检查 GatewayClass 是否存在且有效kubectl get gatewayclass2. 检查 Controller 是否运行kubectl get pods -n3. 查看 Gateway 事件kubectl describe gateway -n4. 检查控制器日志kubectl logs -n -l app问题 2: HTTPRoute 未被接受检查步骤:1. 验证 parentRefs 是否正确kubectl get httproute -o yaml2. 检查 Gateway 是否允许该命名空间的路由kubectl describe gateway -n3. 验证后端服务是否存在kubectl get svc4. 检查 ReferenceGrant (如果跨命名空间)kubectl get referencegrant -A问题 3: 流量未正确路由检查步骤:1. 验证路由规则匹配条件kubectl describe httproute2. 测试后端服务直接访问kubectl run test --rm -i --tty --imagecurlimages/curl –curl http://..svc.cluster.local3. 检查 Gateway 外部 IPkubectl get gateway -o jsonpath‘{.status.addresses}’4. 使用详细输出测试curl -v -H “Host: ” http://6. 生产环境建议6.1 高可用架构部署多个 Controller 副本实现控制器高可用使用多个 Gateway 实例分散负载配置跨区域部署提高灾难恢复能力spec:replicas: 3strategy:type: RollingUpdaterollingUpdate:maxSurge: 1maxUnavailable: 06.2 备份和恢复定期备份 Gateway API 资源配置使用 GitOps 工具(如 ArgoCD、Flux)管理配置建立配置变更审批流程备份所有 Gateway API 资源kubectl get gatewayclass,gateway,httproute,tcproute,referencegrant -A -o yaml gateway-backup.yaml6.3 容量规划关键监控指标:每秒请求数 (RPS)平均/ P95/P99 延迟错误率 (4xx, 5xx)活跃连接数带宽使用率6.4 版本升级策略先在测试环境验证新版本阅读发行说明,了解破坏性变更灰度升级,先升级部分节点保留回滚方案7. 常见应用场景场景 1: 多域名托管apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: multi-domain-routespec:parentRefs:- name: production-gatewayhostnames:- “app1.example.com”- “app2.example.com”- “app3.example.com”rules:- matches:- path:type: PathPrefixvalue: /backendRefs:- name: shared-backendport: 80场景 2: API 网关apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: api-gateway-routespec:parentRefs:- name: production-gatewayhostnames:- “api.example.com”rules:- matches:- path:type: PathPrefixvalue: /usersbackendRefs:- name: user-serviceport: 8080- matches:- path:type: PathPrefixvalue: /ordersbackendRefs:- name: order-serviceport: 8080- matches:- path:type: PathPrefixvalue: /paymentsbackendRefs:- name: payment-serviceport: 8080场景 3: A/B 测试apiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: ab-test-routespec:parentRefs:- name: production-gatewayhostnames:- “app.example.com”rules:- matches:- path:type: PathPrefixvalue: /backendRefs:- name: variant-aport: 80weight: 50- name: variant-bport: 80weight: 50常见问题与故障排查FAQQ1: Gateway API 和 Ingress 可以共存吗?A: 可以。它们使用不同的资源类型,可以同时在集群中运行。建议逐步迁移,先在新服务中使用 Gateway API。Q2: 如何选择 Gateway Controller 实现?A: 考虑因素:功能需求:是否需要 gRPC、TCP 等高级功能性能要求:吞吐量、延迟指标生态系统:与现有工具链的集成社区活跃度:维护频率、问题响应速度企业支持:是否需要商业支持推荐选择:通用场景: Envoy Gateway、NGINX Gateway Fabric服务网格: Istio高性能: Envoy Gateway简单易用: ContourQ3: Gateway API 的性能如何?A: Gateway API 本身是控制平面,性能取决于数据平面实现(Envoy/Nginx 等)、配置复杂度和硬件资源。现代实现(如 Envoy)可以达到数十万 QPS,延迟在毫秒级。Q4: 如何处理 WebSocket 连接?A: HTTPRoute 天然支持 WebSocket,无需特殊配置。确保后端服务正确处理 Upgrade 头即可。Q5: 可以实现速率限制吗?A: Gateway API v1 标准不直接支持速率限制,但可以通过以下方式实现:Controller 特定扩展(如 Envoy Gateway 的 RateLimitFilter)在服务网格层实现(Istio)使用外部速率限制服务Q6: 如何迁移现有的 Ingress 配置?A: 迁移步骤:分析现有 Ingress 资源映射 Ingress 规则到 HTTPRoute创建对应的 Gateway 资源测试新配置逐步切换流量删除旧 Ingress 资源可以使用官方工具 ingress2gateway 辅助转换:kubectl get ingress -A -o yaml | ingress2gateway -f -Q7: Gateway API 支持哪些 Kubernetes 版本?A: Gateway API v1 需要 Kubernetes 1.22,推荐使用最新的稳定版 Kubernetes 以获得最佳支持。Q8: 如何实现灰度发布的自动化?A: 结合以下工具:Argo Rollouts:渐进式交付Flagger:自动化的金丝雀分析自定义控制器:根据监控指标自动调整权重总结
