Gateway API
🎯 引言
上一篇,我们创建了 orders Service。同一 Namespace 内的其他 Pod 可以通过 http://orders 找到订单服务,但电脑浏览器通常不能直接访问这个集群内部名称。
假设我们希望用户通过 orders.gateway.test 的 /api/info 路径访问订单服务,就需要一个 接收 HTTP 请求的入口,并配置规则:符合这个域名和路径的请求,应该交给哪个 Service。
本篇只解决一个问题: 使用 Gateway API 为 Node.js 订单服务配置 HTTP 入口,并验证路由规则是否生效。 我们先理解请求路径和三个核心资源,再完成本地练习;真实公网入口、域名解析与 HTTPS 不在本篇配置范围内。
🧱 为什么 Service 之外还需要入口
回忆之前的订单服务:
ordersDeployment:保证订单服务的 Pod 按期望数量运行。ordersService:为这些 Pod 提供稳定的 集群内部 访问地址。
但浏览器在集群外部,无法直接依赖集群内部的 orders 服务名。我们希望浏览器只需要记住一个域名,由入口根据请求规则找到订单 Service。
我们的目标是:请求中的域名为 orders.gateway.test、路径为 /api/info 时,让订单服务的 Express 接口处理它。
先区分目标和本次练习: 正式网站需要让域名解析到可访问的入口;本篇使用 kubectl port-forward 和 curl 的 Host 请求头,在自己电脑上 模拟外部 HTTP 请求。即使稍后 curl 成功,也不代表直接在浏览器输入 orders.gateway.test 就能访问。
先看请求应该经过哪些环节:
一次请求是怎样到达订单服务的?
orders.gateway.test/api/info
按照 Gateway 的入口配置和 HTTPRoute 的匹配规则,将请求转给订单 Service
为订单 Pod 提供稳定入口,选择可用后端
这是一张逻辑示意图:请求一般只交给一个符合条件的后端 Pod,不会同时请求两个。
这里有两个关键点:
- Traefik 是实际接收和转发 HTTP 请求的代理程序。
- Gateway API 不是另一个代理程序,而是一套告诉 Traefik 应该怎样处理请求的 Kubernetes 配置资源。
所以,我们要做的不是修改订单服务,而是 为已有的 orders Service 配置入口规则。
🧩 Gateway API 的三个核心资源
假设这次只需要完成一件事: 用户请求 orders.gateway.test/api/info,交给 orders Service。
为了让 Traefik 知道该怎么做,我们需要告诉它三件事:使用哪种入口实现、入口允许什么流量进入、哪些请求交给订单服务。Gateway API 把这些信息分别放在三个资源中:
Gateway API:三个配置,各管一件事
由谁来实现入口?
指定 Traefik 这样的 Controller
入口从哪里接收请求?
定义 HTTP 监听端口,允许路由接入
请求要交给谁?
匹配域名、路径,指向 orders Service
| 资源 | 回答的问题 | 本篇配置 |
|---|---|---|
| GatewayClass | 由谁来实现入口? | 使用 Traefik |
| Gateway | 入口接收什么流量? | 接收 HTTP 请求 |
| HTTPRoute | 哪些请求交给哪个 Service? | 将符合域名和 /api 路径的请求交给 orders |
对应到本篇订单服务, Gateway 会允许 course Namespace 中的 HTTPRoute 使用入口; HTTPRoute 会指定 orders.gateway.test、/api 和 orders Service 之间的匹配关系。
这些都是 配置关系,而不是请求依次穿过的三台服务器。真正接收和转发 HTTP 请求的仍是 Traefik。
后面的 YAML 会一一对应这三个资源。此时先记住它们的职责即可,不必记忆全部字段。
🛠 配置并验证 Gateway API
下面复用前面课程已有的环境:
- kind 集群:
node-course; - Namespace:
course; - Deployment 与 Service:
orders;Service80端口对应订单应用的3000端口。
本篇选择 Traefik 处理 HTTP 请求。环境准备只做两件事:让 Kubernetes 认识 Gateway API 的资源类型,以及安装能够读取这些配置的 Traefik。CRD、Helm 的内部原理不是本篇重点。
本文以 Gateway API v1.6.3 Standard + Traefik Helm Chart 42.3.0 为固定示例组合。Chart 42.x 要求 Kubernetes 1.30 或更新版本;如果前面创建的 kind 集群版本较旧,需要先使用兼容的练习环境。以下安装与更新命令仅用于课程专用集群,不能直接照搬到生产环境。
输出说明: 以下终端输出都是帮助理解命令结果的模拟示例,实际运行时应以自己的集群结果为准。本文配置依据官方文档核对,但尚未在真实 kind 环境中完成端到端测试。
1. 检查订单服务
打开终端:
kubectl config current-context
kubectl get nodes
kubectl get deployment,service -n course
模拟输出:
kind-node-course
NAME STATUS ROLES AGE VERSION
node-course-control-plane Ready control-plane 20m v1.34.0
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/orders 2/2 2 2 10m
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/orders ClusterIP 10.96.42.10 <none> 80/TCP 8m
第一行是当前集群名称。kubectl get nodes 的 VERSION 用来确认 Kubernetes 版本;本示例中的 v1.34.0 只是模拟值。READY 2/2 表示订单 Deployment 当前有两个就绪副本,service/orders 说明订单 Service 已存在。
如果没有这些资源,请先完成前面的 Deployment 和 Service 练习,不需要重新编写 Node.js 代码。
你也可以执行 kubectl get endpointslices -n course -l kubernetes.io/service-name=orders,确认 Service 已发现订单 Pod;如果后端为空,要先检查 Pod 和 Service 标签,不应急于安装网关。
2. 准备 Gateway API 与 Traefik
第一步:安装 Gateway API 资源定义。 普通 kind 集群默认不一定认识 GatewayClass、Gateway 和 HTTPRoute,所以先安装对应资源类型:
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.3/standard-install.yaml
模拟输出(节选):
customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io serverside-applied
这些资源类型已被提交给集群。这里的 CRD 是“自定义资源定义”,可以暂时理解为给 Kubernetes 增加新的资源类型。
第二步:安装 Traefik。 使用 Helm 安装入口程序。Helm 是 Kubernetes 的应用安装工具;如果还没有 Helm,macOS 可执行 brew install helm,其他系统参考 官方安装说明。
helm repo add traefik https://traefik.github.io/charts
helm repo update
helm upgrade --install traefik traefik/traefik \
--version 42.3.0 \
--namespace traefik --create-namespace \
--set providers.kubernetesGateway.enabled=true \
--set gateway.enabled=false \
--set gatewayClass.enabled=false \
--wait --timeout 5m
这里只需要理解:--version 42.3.0 固定 Chart 版本;providers.kubernetesGateway.enabled=true 让 Traefik 读取 Gateway API 资源;两个 enabled=false 阻止 Chart 自动创建 Gateway 和 GatewayClass,方便下一节由我们自己创建, 并不是关闭 Gateway API。如果此前已安装同名 Helm Release,upgrade --install 会更新它,因此不要在其他集群随意执行。
首次安装成功时的模拟输出(节选):
Release "traefik" does not exist. Installing it now.
NAME: traefik
NAMESPACE: traefik
STATUS: deployed
再检查 Traefik 是否运行,以及有没有对外提供 HTTP 的 80 端口:
kubectl get pods -n traefik
kubectl get service traefik -n traefik
模拟输出(按命令顺序,只保留重点):
NAME READY STATUS RESTARTS AGE
traefik-6f8c9d7b5-abcde 1/1 Running 0 40s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
traefik LoadBalancer 10.96.88.20 <pending> 80:30080/TCP,443:30443/TCP 1m
Traefik Pod 已就绪;在普通 kind 集群中,外部地址显示 <pending> 并不妨碍后面通过本机 port-forward 测试。此时只是入口程序准备好了,还没有告诉它要把请求交给 orders Service。
3. 编写 Gateway API 配置
我们已经有了 orders Service,现在要回答三个问题: 谁实现入口?入口接收什么请求?请求交给谁? 按这个顺序认识三个资源,再把它们合并进一个文件。
第一个:GatewayClass——选择 Traefik。
kind: GatewayClass
metadata:
name: traefik-course
spec:
controllerName: traefik.io/gateway-controller
controllerName 指定由哪种 Controller 实现这一类 Gateway。本例选 Traefik,并把 GatewayClass 命名为 traefik-course。
第二个:Gateway——设置 HTTP 入口。
kind: Gateway
metadata:
name: orders-gateway
namespace: course
spec:
gatewayClassName: traefik-course
listeners:
- name: http
protocol: HTTP
port: 8000
allowedRoutes:
namespaces:
from: Same
gatewayClassName 指向刚才创建的 GatewayClass;listeners 描述入口接收 HTTP 请求,port: 8000 对应本例 Traefik 的 web 入口。from: Same 表示只允许与这个 Gateway 处于同一 Namespace 的路由绑定它。这里 Gateway 在 course Namespace,所以本篇的 HTTPRoute 也放在 course。
第三个:HTTPRoute——选择订单服务。
kind: HTTPRoute
metadata:
name: orders-route
namespace: course
spec:
parentRefs:
- name: orders-gateway
hostnames:
- orders.gateway.test
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: orders
port: 80
parentRefs 指向 orders-gateway;hostnames 和 PathPrefix: /api 分别匹配域名和 URL 路径;backendRefs 指定请求最终交给 orders Service 的 80 端口。Express 本来就有 /api/info 接口,所以这里 不需要改写请求路径。
上面三段只截取了重点字段, 不要单独复制执行。下面才是可以保存和提交的完整配置。
创建 gateway-api.yaml:
# ① 指定 Traefik 实现入口
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: traefik-course
spec:
controllerName: traefik.io/gateway-controller
---
# ② 创建 HTTP 入口
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: orders-gateway
namespace: course
spec:
gatewayClassName: traefik-course
listeners:
- name: http
protocol: HTTP
port: 8000
allowedRoutes:
namespaces:
from: Same
---
# ③ 指定域名、路径与后端 Service
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: orders-route
namespace: course
spec:
parentRefs:
- name: orders-gateway
hostnames:
- orders.gateway.test
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: orders
port: 80
三个资源放在同一个 YAML 文件中,使用 --- 分隔。每个资源都补上了 Kubernetes 识别所需的 apiVersion。
接下来实操会出现几个端口,先看图,不必死记数字:
一次请求经过的五个端口
你的电脑
curl 通过 port-forward 发起测试请求
Traefik Service
将请求交给 Traefik 代理
Traefik HTTP 入口
根据 Gateway 和 HTTPRoute 配置匹配请求
orders Service
提供订单应用的稳定访问入口
订单 Pod
Express 应用实际监听的端口
示意图基于本文示例配置。两个 80 分别属于不同的 Service,并不是同一个端口对象。
这张图对应本次练习:本机 8081 → Traefik Service 80 → Traefik 内部 HTTP 入口 8000 → orders Service 80 → 订单 Pod 3000。图中两个 80 属于 不同的 Service。8000 是本篇 Traefik 的配置,不是 Gateway API 的固定端口。
4. 创建并查看结果
kubectl apply -f gateway-api.yaml
模拟输出:
gatewayclass.gateway.networking.k8s.io/traefik-course created
gateway.gateway.networking.k8s.io/orders-gateway created
httproute.gateway.networking.k8s.io/orders-route created
这表示三个资源已提交给 Kubernetes。 提交成功不等于请求一定能访问,还需要确认 Traefik 接受了配置:
第一步:检查 GatewayClass。
kubectl get gatewayclass traefik-course
模拟输出:
NAME CONTROLLER ACCEPTED AGE
traefik-course traefik.io/gateway-controller True 25s
ACCEPTED=True 表示 Traefik 已接受这个 GatewayClass。
第二步:检查 Gateway。
kubectl get gateway orders-gateway -n course
模拟输出(ADDRESS 在 kind 中可能为空):
NAME CLASS ADDRESS PROGRAMMED AGE
orders-gateway traefik-course True 20s
PROGRAMMED=True 表示 Controller 报告入口已完成相应配置;这仍不等于 HTTP 请求一定能成功。
第三步:检查 HTTPRoute。
kubectl describe httproute orders-route -n course
模拟输出(仅截取状态部分,省略其他字段):
Status:
Parents:
Parent Ref:
Name: orders-gateway
Conditions:
Type: Accepted
Status: True
Type: ResolvedRefs
Status: True
Parent Ref 显示这条路由关联了 orders-gateway。Accepted=True 表示路由已被接受,ResolvedRefs=True 表示后端引用能被解析。最后还需要真正发送 HTTP 请求,验证请求是否到达应用。
5. 实际访问订单服务
在 kind 中,我们使用端口转发让电脑暂时访问 Traefik。由于没有配置域名解析和公网负载均衡器, 即使测试成功,也不能直接在浏览器中输入 orders.gateway.test 来访问。
终端 A:
kubectl port-forward -n traefik service/traefik 8081:80
模拟输出:
Forwarding from 127.0.0.1:8081 -> 8000
Forwarding from [::1]:8081 -> 8000
这里的端口对应关系可以回看上面的 端口示意图。port-forward 只是在你的电脑和 Traefik 之间建立临时测试通道, 不是为真实公网用户配置了正式访问入口。
终端 B(保持终端 A 不关闭):
curl -i -H 'Host: orders.gateway.test' http://127.0.0.1:8081/api/info
模拟响应:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"service":"orders","version":"v1"}
Host 请求头指定本次 HTTP 请求使用的域名,让 Traefik 能匹配 HTTPRoute 中的 orders.gateway.test;因此本地测试无需修改电脑的 hosts 文件。看到 200 OK,且 JSON 与前面 Service 课程的 /api/info 响应一致,才说明请求到达了 Node.js 应用。 这里验证的是本地临时入口,并不是公网域名已经配置完成。
再把路径改成不匹配的 /other:
curl -i -H 'Host: orders.gateway.test' http://127.0.0.1:8081/other
在没有其他规则匹配时,可能看到:
HTTP/1.1 404 Not Found
404 page not found
这次不是 Pod 故障,而是 HTTPRoute 只匹配 /api 开头的路径,/other 没有命中规则。
测试结束后,在终端 A 按 Ctrl+C 停止端口转发。Gateway API 的资源仍保留在集群中。
❓ 知识问答
Q:已经有 Service,为什么还需要 Gateway API?
Service 为一组 Pod 提供稳定的集群内访问入口;Gateway API 则帮助我们配置外部 HTTP 请求如何进入,并按域名和路径选择 Service。
Q:GatewayClass、Gateway 和 HTTPRoute 会分别启动三个代理程序吗?
不会。它们是配置资源。真正处理请求的是 Traefik 等兼容 Controller 所管理的代理程序。
Q:Ingress 是什么?还必须学吗?
Ingress 是另一套 Kubernetes HTTP/HTTPS 入口配置 API,已有项目仍然使用它。新项目可以优先评估 Gateway API。 学会本篇并不要求你先掌握 Ingress,也不需要为了同一个入口同时配置两套资源。
🧪 小练习
修改 gateway-api.yaml 中 HTTPRoute 的匹配路径:
value: /orders
重新执行:
kubectl apply -f gateway-api.yaml
保持或者重新启动端口转发,再访问原来的 /api/info:
curl -i -H 'Host: orders.gateway.test' http://127.0.0.1:8081/api/info
因为路径不再匹配,且假设没有其他路由规则,预期得到 404。 这说明请求被入口规则拦住,并不是订单服务代码出错。
最后把路径恢复成 /api,重新执行 kubectl apply,确认接口恢复返回 JSON。
验收标准: 能用自己的话解释 GatewayClass、Gateway、HTTPRoute 三者的职责,并通过修改路径观察正常访问与 404 的区别。
🎉 恭喜你!你已经理解为什么订单 Service 之外还需要 HTTP 入口,并使用 Gateway API 完成了从本机模拟 HTTP 请求到 Node.js Pod 的访问验证。
