Gateway API 新一代网络 API
本页介绍如何在 Kuboard 中使用 Gateway API 创建第一个 HTTP 网关，并完成跨名称空间引用授权。适用于集群管理员与应用开发者。
Gateway API 是 Kubernetes 官方推出的新一代流量路由 API，目标是逐步取代 Ingress：把 Ingress「一个对象同时描述入口与路由」的做法，拆成 网关类 → 网关 → 路由 三级，集群运维与应用开发者各管各的、互不越权。
| 对比项 | Ingress | Gateway API |
|---|---|---|
| 对象模型 | 一个对象同时承担「入口 + 路由」 | 拆分为 网关类 / 网关 / 路由 三级 |
| 职责分工 | 运维与应用开发共用同一对象 | 运维管网关类与网关，开发者只管路由 |
| 协议支持 | 以 HTTP / HTTPS 为主 | HTTP、HTTPS、TLS、TCP、UDP、gRPC |
| 跨名称空间 | 支持有限 | 通过引用授权（ReferenceGrant）显式放行 |
与 Ingress 的关系
两者可以共存：已有 Ingress 不受影响，新入口建议优先用 Gateway API。传统 Ingress 见 服务与 Ingress，网络隔离见 NetworkPolicy。
前置条件
- 安装 Gateway API 的 CRD（CustomResourceDefinition）：
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml- 安装网关控制器（任选其一，不同实现的特性支持略有差异；创建网关类时「控制器名称」填其预设值）：
| 控制器 | 控制器名称预设值 |
|---|---|
| Istio | istio.io/gateway-controller |
| Envoy Gateway | gateway.envoyproxy.io/gateway-controller |
| Cilium | io.cilium/gateway-controller |
| NGINX Gateway Fabric | gateway.nginx.org/nginx-gateway-controller |
| ingress-nginx | k8s.io/ingress-nginx（需以 --enable-gateway-api 参数启动） |
Kuboard 中找不到「网关」菜单怎么办
- 菜单路径为 服务与网络 → 网关。集群未安装 Gateway API CRD 时，菜单仍会显示，但列表页为空；
- 点击 创建（+） 时，Kuboard 会先探测资源可用性，探测不通过则弹出 「资源不可用」 对话框，其中给出一键复制的安装命令（即上面的
standard-install.yaml）、组件说明与官方文档链接； - 安装完成后刷新页面即可正常使用。
创建第一个 HTTP 网关
以最常见场景为例：让 example.com 的 HTTP 流量经过网关转发到名称空间 web 中的 Service my-web，共四步。网关类与网关通常由集群管理员创建，应用开发者主要创建路由并挂到已有网关上。
步骤 1：创建网关类（GatewayClass）
- 进入 服务与网络 → 网关 → 网关类，点击 创建（+）；
- 填写：
| 字段 | 说明 | 示例 |
|---|---|---|
| 名称 | 网关类名称 | example-gateway-class |
| 控制器名称 | 必填。下拉选择主流控制器，也可手动输入 | istio.io/gateway-controller |
| 描述 | 可选，256 字以内 |
- 点击 保存 → 在 预览 YAML 对话框确认 → 提交后跳转详情页，列表页出现该网关类，详情页状态显示控制器已接管即为成功（网关类为集群级资源，创建时不需要选择名称空间）。
高级项：参数引用
当控制器需要额外配置对象（如配置参数 CRD）时，在表单中展开「启用参数引用（高级）」并填写组 / 类型 / 名称即可。多数场景用不到，保持关闭。
步骤 2：创建网关（Gateway）
- 进入 服务与网络 → 网关 → 网关，点击 创建（+），填写 名称 与 网关类名称（填步骤 1 的名称）；
- 在 监听器 表格中点击 添加监听器，至少配置一个：
| 字段 | 说明 | 示例 |
|---|---|---|
| 名称 | 监听器名称 | http-listener |
| 端口 | 1 - 65535 | 80 |
| 协议 | HTTP / HTTPS / TCP / TLS / UDP | HTTP |
| 主机名 | 可选；填写后该监听器只接收匹配此主机名的流量 | example.com |
| 允许的路由 | 允许哪些名称空间的路由接入：Same（仅本名称空间）/ All（全部）/ Selector（按标签选择） | Same |
- 地址 可选：不填时由控制器自动分配，创建后在详情页查看实际地址；保存并确认预览 YAML。详情页状态显示控制器已接管该网关即为成功；若显示未接管，见文末排障。
步骤 3：创建 HTTP 路由（HTTPRoute）
- 进入 服务与网络 → 网关 → HTTP 路由，点击 创建（+），填写 名称（如
my-web-route）； - 在 父级引用 中点击 添加父级引用，指向步骤 2 的网关：
| 字段 | 说明 |
|---|---|
| 名称 | 必填，网关名称 |
| 名称空间 | 网关所在名称空间（与路由同名称空间时可不填） |
| 配置节名称 / 端口 | 可选，精确指定挂到某个监听器 |
- 在 主机名 中输入
example.com（回车确认；不填则匹配该网关下所有主机名）；在 路由规则 中点击 添加路由规则，选中该规则后在下方「已选规则」区域配置 后端引用：
| 字段 | 说明 | 示例 |
|---|---|---|
| 类型 | 后端资源类型，默认 Service | Service |
| 名称 | 选择名称空间中的 Service | my-web |
| 名称空间 | Service 所在名称空间；跨名称空间时需引用授权（见下文） | web |
| 端口 | Service 的端口 | 80 |
| 权重 | 多后端时按权重分配流量（默认 1） | 1 |
- 保存并确认（结果：列表页出现该路由，详情页关联网关页签显示它挂到了哪个网关）。匹配条件（路径 / 请求头 / 查询参数 / 方法）与过滤器（URL 重写、请求头修改）为高级能力：表单只显示数量，具体内容需在 YAML 中编辑，多数场景只需主机名 + 后端引用。
步骤 4：验证
- HTTP 路由详情页 → 状态：显示已被控制器接受即规则生效；网关详情页 → 关联路由：能看到
HTTPRoute / my-web-route； - 网关详情页 → 地址：确认网关对外地址（由控制器分配）；
- 用
curl验证流量：
curl -H "Host: example.com" http://<网关地址>/能看到 my-web 的响应即成功。
ReferenceGrant 跨命名空间引用授权
Gateway API 的默认策略是：名称空间是信任边界，路由只能引用自己名称空间内的对象，跨名称空间引用一律被拒绝，除非被引用对象所在名称空间中有对应的引用授权。两种典型场景必须创建它：路由要转发到其他名称空间的 Service，或要引用其他名称空间的网关（如统一网关所在的 gateway-system）。
进入 服务与网络 → 网关 → 引用授权（即 ReferenceGrant），点击 创建（+），填写 名称（如 allow-web-to-my-web），然后配置下面两张表：来源（From）声明「谁」被允许引用，目标（To）声明「可以引用什么」。
| 字段 | 说明 | 示例 |
|---|---|---|
| 组 | 引用方资源所属组 | gateway.networking.k8s.io |
| 类型 | 引用方资源类型 | HTTPRoute |
| 名称空间 | 引用方所在的名称空间 | web |
| 字段 | 说明 | 示例 |
|---|---|---|
| 组 | 被引用资源所属组（核心组留空） | "" |
| 类型 | 被引用资源类型 | Service |
| 名称 | 可选，限定具体对象；不填表示该名称空间内全部 | my-web |
引用授权放在哪个名称空间
引用授权必须创建在被引用对象所在的名称空间。例如名称空间 A 的路由要引用名称空间 B 的 Service，就在名称空间 B 中创建，来源指向 A 的 HTTP 路由，目标指向 B 的 Service。
各类 Route 适用场景对比
| 类型 | 处理层级 | 主机名 | 规则能力 | 适用场景 |
|---|---|---|---|---|
| HTTPRoute（HTTP 路由） | L7 | 有 | 路径 / 请求头 / 查询参数 / 方法匹配、过滤器、按权重多后端 | 网站、REST 服务、按域名分流 |
| GRPCRoute（gRPC 路由） | L7 | 有 | 按方法匹配、过滤器 | gRPC 微服务 |
| TLSRoute（TLS 路由） | L4 | 有（按 SNI 分流） | 仅后端转发 | TLS 终结（HTTPS 回源）、按证书域名转发 |
| TCPRoute（TCP 路由） | L4 | 无 | 仅后端转发 | 数据库、消息队列等 TCP 服务 |
| UDPRoute（UDP 路由） | L4 | 无 | 仅后端转发 | DNS、日志采集等 UDP 服务 |
- 按域名 / 路径 / 请求头精细转发 → HTTPRoute；gRPC 流量 → GRPCRoute；
- 只按端口 + 域名（SNI）转发 TLS 流量 → TLSRoute；四层裸流量 → TCPRoute / UDPRoute（无主机名，规则只有后端引用）。
排障：路由不生效看哪里
路由不生效时，先看状态、再看事件：
- 网关详情页 → 状态与路由详情页 → 状态：看不正常（失败 / 被拒绝）的行，「原因」与「消息」会直接说明问题；若路由显示「控制器未上报状态」，说明控制器没有处理它；
- 核对关联关系：路由详情页 → 关联网关 确认指向了正确的网关；网关详情页 → 关联路由 确认路由确实在列表中。
常见原因速查：
| 现象 | 常见原因 |
|---|---|
| 网关状态为空 / 未接管 | 网关控制器未安装或未启动；先按「前置条件」检查 |
| 路由状态异常（被拒绝） | 监听器配置不合法（端口冲突、协议不支持）、网关类名称不存在 |
| 路由挂不上网关 | 父级引用名称 / 名称空间写错；监听器协议与路由类型不匹配；被监听器的「允许的路由」拒绝 |
| 跨名称空间转发失败 | 缺少引用授权（在被引用 Service 所在名称空间创建） |
| 指定了主机名但访问 404 | 路由的主机名与监听器主机名不匹配；或请求的 Host 不在路由的主机名列表内 |
| 后端连接失败 | 后端引用的端口写错、Service 不存在、权重为 0 |
事件怎么看
状态信息不足时，打开对应对象的 事件 页签查看控制器报错。Kuboard 的对象列表与详情页均提供「事件」入口。