容器与云原生 / 系统课时
使用 Kubernetes Gateway API 接入流量
使用 Kubernetes Gateway API 接入流量
本篇完成一个可直接验证的入口:由 Istio 实现 Kubernetes Gateway API,用 Gateway 声明 HTTP 监听器,再用 HTTPRoute 把外部请求转发到集群内 Service,并通过状态条件与真实请求确认配置已经生效。
学习目标
- 识别
GatewayClass、Gateway、HTTPRoute与 Service 的职责边界。 - 配置跨命名空间的入口监听器与 HTTP 路由。
- 通过状态条件和实际请求验证路由已经生效。
检查 Gateway API 与 Istio 实现
开始前需要一个已安装 Istio 控制面的 Kubernetes 集群,并确保 Gateway API CRD 和名为 istio 的 GatewayClass 已存在。先检查资源是否就绪,避免后续把“CRD 不存在”误判成路由配置错误。
kubectl get crd gateways.gateway.networking.k8s.io httproutes.gateway.networking.k8s.io -o name
kubectl get gatewayclass istio -o name预期输出:
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io
gatewayclass.gateway.networking.k8s.io/istio如果任一资源不存在,应先补齐 Gateway API CRD 或修复 Istio 安装;不要自行创建同名 GatewayClass 来绕过检查,因为 spec.controllerName 必须与实际的 Istio Gateway API 控制器匹配。
理解入口对象如何挂接
GatewayClass 决定由哪个控制器实现网关;Gateway 定义监听端口、协议、主机名以及允许哪些 Route 挂接;HTTPRoute 通过 parentRefs 绑定 Gateway,再把匹配到的请求交给 backendRefs 指向的 Service。
本例把 Gateway 放在 mesh-ingress 命名空间,把应用和 Route 放在 demo-app。因此监听器通过 allowedRoutes.namespaces.from: All 允许其他命名空间的 Route 挂接。后端 Service 与 HTTPRoute 位于同一命名空间,因此后端引用不需要 ReferenceGrant。

创建入口与 HTTPRoute
把下面内容保存为 gateway-api-ingress.yaml。示例同时创建测试应用、入口 Gateway 和 Route,因此不依赖本章其他课时的资源。监听器与 Route 都声明 app.example.com,只有两者主机名能够相交时,Route 才可能被监听器接受。
apiVersion: v1
kind: Namespace
metadata:
name: mesh-ingress
---
apiVersion: v1
kind: Namespace
metadata:
name: demo-app
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
namespace: demo-app
spec:
replicas: 1
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.27-alpine
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: web
namespace: demo-app
spec:
selector:
app: web
ports:
- port: 80
targetPort: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: public-gateway
namespace: mesh-ingress
spec:
gatewayClassName: istio
listeners:
- name: http
hostname: app.example.com
port: 80
protocol: HTTP
allowedRoutes:
namespaces:
from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: web-route
namespace: demo-app
spec:
parentRefs:
- name: public-gateway
namespace: mesh-ingress
hostnames:
- app.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: web
port: 80应用配置:
kubectl apply -f gateway-api-ingress.yaml首次执行预期输出:
namespace/mesh-ingress created
namespace/demo-app created
deployment.apps/web created
service/web created
gateway.gateway.networking.k8s.io/public-gateway created
httproute.gateway.networking.k8s.io/web-route created重复执行时 created 可能变为 configured 或 unchanged,这不代表失败。
验证监听器与路由状态
先等待 Gateway 被控制器编程,再读取 HTTPRoute 对父 Gateway 的 Accepted 条件。只有“对象创建成功”还不够;如果主机名不相交、监听器拒绝该命名空间或引用关系不成立,状态条件会直接暴露问题。
kubectl wait -n mesh-ingress --for=condition=programmed gateway/public-gateway --timeout=90s
kubectl get httproute web-route -n demo-app -o 'jsonpath={.status.parents[0].conditions[?(@.type=="Accepted")].status}{"\n"}'预期输出:
gateway.gateway.networking.k8s.io/public-gateway condition met
True如果集群能为 Gateway 分配可访问地址,再发送带正确 Host 的请求:
GATEWAY_ADDRESS="$(kubectl get gateway public-gateway -n mesh-ingress -o 'jsonpath={.status.addresses[0].value}')"
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: app.example.com' "http://${GATEWAY_ADDRESS}/"预期输出:
200GATEWAY_ADDRESS 的实际值可能是 <IP> 或 <HOSTNAME>;本地集群如果没有可用的负载均衡实现,Gateway 状态可能正常而外部地址为空,此时应先解决入口暴露方式,而不是修改 HTTPRoute。
配置入口时应把“监听”和“转发”分开检查:先确认 Gateway 已 Programmed,再确认 Route 已 Accepted,最后用真实请求验证数据面。这样可以快速区分控制面未接受配置、入口地址不可达和后端服务异常。