Gateway API

从浏览器访问 Kubernetes 订单服务的问题出发,理解 Gateway API 的核心资源,并使用 Traefik 配置和验证 HTTP 入口。

🎯 引言

上一篇,我们创建了 orders Service。同一 Namespace 内的其他 Pod 可以通过 http://orders 找到订单服务,但电脑浏览器通常不能直接访问这个集群内部名称。

假设我们希望用户通过 orders.gateway.test 的 /api/info 路径访问订单服务,就需要一个 接收 HTTP 请求的入口,并配置规则:符合这个域名和路径的请求,应该交给哪个 Service。

本篇只解决一个问题: 使用 Gateway API 为 Node.js 订单服务配置 HTTP 入口,并验证路由规则是否生效。 我们先理解请求路径和三个核心资源,再完成本地练习;真实公网入口、域名解析与 HTTPS 不在本篇配置范围内。


🧱 为什么 Service 之外还需要入口

回忆之前的订单服务:

  • orders Deployment:保证订单服务的 Pod 按期望数量运行。
  • orders Service:为这些 Pod 提供稳定的 集群内部 访问地址。

但浏览器在集群外部,无法直接依赖集群内部的 orders 服务名。我们希望浏览器只需要记住一个域名,由入口根据请求规则找到订单 Service。

我们的目标是:请求中的域名为 orders.gateway.test、路径为 /api/info 时,让订单服务的 Express 接口处理它。

先区分目标和本次练习: 正式网站需要让域名解析到可访问的入口;本篇使用 kubectl port-forward 和 curl 的 Host 请求头,在自己电脑上 模拟外部 HTTP 请求。即使稍后 curl 成功,也不代表直接在浏览器输入 orders.gateway.test 就能访问。

先看请求应该经过哪些环节:

一次请求是怎样到达订单服务的?

浏览器 / curl

orders.gateway.test/api/info

发送 HTTP 请求
Traefik(真正处理请求的代理)

按照 Gateway 的入口配置和 HTTPRoute 的匹配规则,将请求转给订单 Service

Gateway
提供入口设置
HTTPRoute
提供匹配规则
上面两项是 Traefik 读取的配置,并非 HTTP 流经的服务器
匹配成功后转发
orders Service :80

为订单 Pod 提供稳定入口,选择可用后端

发送到其中一个后端
订单 Pod A
Node.js :3000
订单 Pod B
Node.js :3000

这是一张逻辑示意图:请求一般只交给一个符合条件的后端 Pod,不会同时请求两个。

这里有两个关键点:

  1. Traefik 是实际接收和转发 HTTP 请求的代理程序。
  2. Gateway API 不是另一个代理程序,而是一套告诉 Traefik 应该怎样处理请求的 Kubernetes 配置资源。

所以,我们要做的不是修改订单服务,而是 为已有的 orders Service 配置入口规则。


🧩 Gateway API 的三个核心资源

假设这次只需要完成一件事: 用户请求 orders.gateway.test/api/info,交给 orders Service。

为了让 Traefik 知道该怎么做,我们需要告诉它三件事:使用哪种入口实现、入口允许什么流量进入、哪些请求交给订单服务。Gateway API 把这些信息分别放在三个资源中:

Gateway API:三个配置,各管一件事

GatewayClass

由谁来实现入口?

指定 Traefik 这样的 Controller

Gateway

入口从哪里接收请求?

定义 HTTP 监听端口,允许路由接入

HTTPRoute

请求要交给谁?

匹配域名、路径,指向 orders Service

注意:它们是 Kubernetes 中的配置资源,不是三个正在运行的代理程序。真正接收和转发 HTTP 请求的是 Traefik。
资源回答的问题本篇配置
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;Service 80 端口对应订单应用的 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 发起测试请求

:8081

Traefik Service

将请求交给 Traefik 代理

:80

Traefik HTTP 入口

根据 Gateway 和 HTTPRoute 配置匹配请求

:8000

orders Service

提供订单应用的稳定访问入口

:80

订单 Pod

Express 应用实际监听的端口

:3000

示意图基于本文示例配置。两个 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 的访问验证。