CN
EN
在Kubernetes中，Ingress曾经是暴露服务给外部流量的标准方案。但随着微服务和多租户场景的复杂化，Ingress的局限性越来越明显：注解（Annotations）依赖特定控制器的实现，可移植性差；路由表达能力有限，难以精细控制流量切分和跨命名空间引用。Gateway API正是Kubernetes SIG-Network为取代Ingress而设计的下一代服务网络标准。它通过角色分离（基础设施提供者、集群运维、应用开发者）和强类型化的CRD，让网关配置变得可移植、可组合、可扩展。
本文手把手带你完成Gateway API的安装与第一个流量路由的配置，全程基于2026年仍在积极维护的标准版本。
前置条件：集群与工具就绪
在开始之前，确认三件事：一个可用的Kubernetes集群（版本建议1.25以上），`kubectl`已正确配置并指向该集群，以及具备`cluster-admin`权限（安装CRD和控制器需要）。
Gateway API本身只是资源定义（CRD），它定义了`GatewayClass`、`Gateway`、`HTTPRoute`等API对象。要让这些对象真正驱动数据面流量，还需要一个控制器实现（Controller）。两者的关系类似于“接口”与“实现”：Gateway API是标准接口，Envoy Gateway、NGINX Gateway Fabric、Cilium等是具体的实现。
第一步：安装Gateway API标准CRD
Gateway API的CRD不会随Kubernetes集群默认安装，必须手动部署。官方提供标准通道（Standard Channel）和实验通道（Experimental Channel），生产环境建议从标准通道开始，它包含了稳定可用的核心资源：`GatewayClass`、`Gateway`、`HTTPRoute`、`GRPCRoute`等。
执行以下命令安装标准CRD（以v1.4.0为例，可在官方Releases页面确认最新稳定版本）：
kubectl apply-f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml安装完成后，用以下命令验证核心CRD是否已就绪：
kubectl get crd gateways.gateway.networking.k8s.io httproutes.gateway.networking.k8s.io如果两个CRD都出现在输出中，说明Gateway API的资源定义已经成功注册到集群。
第二步：选择并安装控制器
控制器是Gateway API从声明式配置转化为实际流量处理的核心。2026年的主流选择包括Envoy Gateway、NGINX Gateway Fabric和Cilium。三者各有侧重，选择哪一个取决于你的集群现状和团队熟悉度。
Envoy Gateway是Gateway API的参考实现之一，以Envoy Proxy作为数据面，社区活跃、文档完善，适合希望获得标准化Gateway API体验、且不绑定特定厂商CRD的场景。通过Helm安装：
helm install eg oci://docker.io/envoyproxy/gateway-helm\
--version v1.6.3\
-n envoy-gateway-system\
--create-namespace等待控制器就绪：
kubectl wait--namespace envoy-gateway-system\
--for=condition=ready pod\
--selector=control-plane=envoy-gateway\
--timeout=90sNGINX Gateway Fabric适合已经在使用NGINX作为入口的团队。它使用NGINX作为数据面，对NGINX的配置模型和调优经验可以平滑迁移。安装方式同样基于Helm：
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric\
--create-namespace-n nginx-gatewayCilium适合已经使用Cilium作为CNI的集群。Cilium的Gateway API支持内置于其自身的数据面中，不需要额外部署独立的代理组件，架构更简洁。但需要确保Cilium已启用`kubeProxyReplacement=true`和`l7Proxy=true`（后者默认开启），并通过Helm设置`gatewayAPI.enabled=true`来激活控制器。
第三步：创建GatewayClass与Gateway
控制器就绪后，下一步是定义“谁来处理流量”以及“在哪里监听”。
`GatewayClass`声明了使用哪个控制器实现。以Envoy Gateway为例，安装后通常会自带一个默认的GatewayClass（名称为`eg`），可以通过`kubectl get gatewayclass`确认。如果没有现成的，需要手动创建：
yaml
apiVersion:gateway.networking.k8s.io/v1
kind:GatewayClass
metadata:
name:eg
spec:
controllerName:gateway.envoyproxy.io/gatewayclass-controller`Gateway`定义了监听端口和协议。一个最小的HTTP监听配置如下：
yaml
apiVersion:gateway.networking.k8s.io/v1
kind:Gateway
metadata:
name:my-gateway
namespace:default
spec:
gatewayClassName:eg
listeners:
-name:http
protocol:HTTP
port:80创建后，控制器会为这个Gateway自动创建数据面工作负载（如Envoy Proxy Pod）和对应的Service。用`kubectl get gateway my-gateway`确认`PROGRAMMED`或`ADDRESS`状态已就绪。
第四步：用HTTPRoute将流量路由到后端服务
Gateway只是“入口”，`HTTPRoute`才是“路由规则”。它根据主机名和路径，将请求转发到后端的Service。
假设集群中已经有一个名为`my-app`的Service，监听80端口，下面的HTTPRoute将所有发往`www.example.com`的请求路由到该服务：
yaml
apiVersion:gateway.networking.k8s.io/v1
kind:HTTPRoute
metadata:
name:my-route
namespace:default
spec:
parentRefs:
-name:my-gateway
hostnames:
-"www.example.com"
rules:
-matches:
-path:
type:PathPrefix
value:/
backendRefs:
-name:my-app
port:80`parentRefs`将这条路由绑定到上面创建的Gateway。`matches`定义了匹配条件，`backendRefs`指向实际处理请求的Service。
第五步：验证流量是否真正打通
最直接的验证方式是通过Gateway的地址发起请求。先获取Gateway对外暴露的地址：
kubectl get gateway my-gateway-o jsonpath='{.status.addresses[0].value}'如果地址是一个IP，直接用`curl`指定Host头访问：
curl--header"Host:www.example.com"http://<GATEWAY_IP>/如果地址是主机名（某些云平台的负载均衡器返回主机名），则将`http://<GATEWAY_IP>`替换为`http://<GATEWAY_HOSTNAME>`。
请求返回后端应用的响应内容，说明从Gateway到HTTPRoute再到Service的整条链路已经打通。
常见问题与排查思路
Gateway一直处于`PROGRAMMED:False`状态。检查`kubectl describe gateway<名称>`的Events和Conditions字段。常见原因是控制器未正确安装、GatewayClass的`controllerName`与实际安装的控制器不匹配，或者控制器Pod未能正常启动。
HTTPRoute创建后，访问仍然返回404。确认`parentRefs`中的Gateway名称和命名空间是否准确，`hostnames`是否与请求的Host头完全一致（包括是否有尾部点号），以及`backendRefs`指向的Service是否存在且处于Running状态。
CRD版本与控制器不兼容。Gateway API的不同版本之间可能存在资源字段的差异。安装控制器之前，应查阅其文档中标注的兼容Gateway API版本范围。例如，Cilium 1.19需要Gateway API v1.4.1的CRD。版本不匹配是“CRD已安装、控制器已运行，但路由不生效”的常见根因。
底层网络：Gateway API的流量最终要跑在稳定的网络上
Gateway API解决的是Kubernetes集群内部的流量编排问题，但集群最终仍然要对外提供服务。如果底层云服务器的网络线路在晚高峰丢包严重，即便Gateway和HTTPRoute配置完美，外部用户看到的仍然是超时和重试。
Jtti的云服务器方案为Kubernetes集群的对外暴露提供了稳定的网络底座。香港及美国节点接入CN2 GIA精品线路，三网直连优化，晚高峰丢包率稳定在0.5%以下。Gateway数据面（如Envoy Proxy）与外部客户端之间的长连接不会因为跨境链路的抖动而频繁中断，HTTPRoute配置的路由规则才能真正兑现为用户的流畅访问。全系标配独享带宽，确保多个Gateway实例并行时的网络吞吐不被“邻居”挤占。企业级NVMe SSD保障了集群节点上镜像拉取和日志写入的I/O响应，Gateway控制器的配置同步和路由表下发不会因为磁盘阻塞而延迟。终身循环折扣政策让长期运行Kubernetes基础设施的成本完全可预期。
Gateway API的安装本身并不复杂：装CRD、选控制器、建Gateway、配HTTPRoute。真正决定它能否在生产环境中稳定运行的，是控制器与CRD的版本匹配、路由规则的准确绑定，以及底层网络能否把Gateway处理后的流量可靠地送到用户手中。把这四步走完，再用`curl`完成一次端到端的验证，你就拥有了一个比Ingress更现代、更可移植的流量入口。
