Kubernetes Gateway API 跨命名空间引用为何需要 ReferenceGrant

Kubernetes Gateway API 的跨命名空间引用不是“写上 namespace 就能通”。我第一次把公共 Gateway 和业务 HTTPRoute 拆到不同命名空间时，最容易误判的是：Gateway 已经允许跨命名空间路由，但 HTTPRoute 指向另一个命名空间的 Service 仍然没有生效。原因在于这里有两个独立的信任边界：路由能否附加到 Gateway，以及路由能否引用目标命名空间里的 Service。

官方地址：https://gateway-api.sigs.k8s.io/

一句话记忆：allowedRoutes 管“哪些路由可以挂到 Gateway”，ReferenceGrant 管“目标命名空间是否允许外部资源引用自己”。跨命名空间引用默认拒绝，授权要由被引用对象的命名空间所有者明确声明。

先把 Gateway、HTTPRoute 和 Service 的边界画清

假设平台团队把 Gateway 放在 edge 命名空间，应用团队把 HTTPRoute 放在 store，后端 Service 还在 store-backend。这时至少有两条不同的关系：

• HTTPRoute.parentRefs 指向 edge 中的 Gateway，这是路由附加关系；
• HTTPRoute.backendRefs 指向 store-backend 中的 Service，这是后端资源引用关系。

Gateway 的监听器默认只接受同命名空间的 Route。要让 store 中的 HTTPRoute 附加到 edge 中的 Gateway，需要在监听器上配置 allowedRoutes。但这一步只解决“路由能不能挂上来”，不等于放行了对别的命名空间 Service 的引用。

ReferenceGrant 为什么要放在目标命名空间

ReferenceGrant 的设计重点是“被引用资源的所有者授权”。如果 store 中的 HTTPRoute 想引用 store-backend 中的 Service，那么授权对象应当创建在 store-backend，而不是创建在 HTTPRoute 所在的 store。

下面的 YAML 只展示授权关系，名称和命名空间可以按自己的集群替换。from 写谁可以发起引用，to 写本命名空间内允许被引用的资源类型：

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-store-route
  namespace: store-backend # 中文注释：授权必须放在被引用 Service 所在命名空间
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: store # 中文注释：只允许 store 命名空间的 HTTPRoute 发起引用
  to:
    - group: ""
      kind: Service # 中文注释：范围收窄到核心 Service，不放行整个资源组

这里没有把某一个 Service 名字写进 to，表示授权该命名空间内符合条件的 Service。生产环境如果只需要少数资源，应结合控制器实现能力和团队权限模型进一步收窄授权，避免把一个临时路由变成长期的跨租户访问通道。ReferenceGrant 解决的是资源引用的信任关系，不会替代 Service、NetworkPolicy 或业务鉴权。

allowedRoutes 和 ReferenceGrant 不是同一把开关

我现在排查这类问题会先把故障拆成两层，而不是反复修改 HTTPRoute：

其中，Gateway 的 allowedRoutes.namespaces.from 决定 Route 的来源命名空间；ReferenceGrant 的 from 与 to 决定跨命名空间引用的来源类型和目标类型。两者都通过后，HTTPRoute 才有机会得到有效的后端解析。

用 status 条件定位到底缺哪一层

示例命令只用于读取资源状态，不把未实际执行的输出当成运行证据。先分别查看 Gateway 和 HTTPRoute 的状态：

# 中文注释：先看路由是否被 Gateway 接受，再看后端引用是否解析成功
kubectl get gateway -n edge public-gateway -o yaml
kubectl get httproute -n store checkout-route -o yaml

# 中文注释：事件只用于补充控制器给出的原因，不替代 status 条件判断
kubectl describe httproute -n store checkout-route

重点看三类信号：

1. parentStatuses 中的 Accepted。如果它不是 true，先回到 Gateway listener 的 allowedRoutes 和 parentRefs。
2. ResolvedRefs。如果它不是 true，优先检查 Service 的命名空间、端口和目标命名空间是否存在正确的 ReferenceGrant。
3. 控制器给出的 reason。不同实现的细节可能不同，不要只凭一个通用错误字符串判断；把资源状态、控制器文档和实际支持的 Gateway API 版本放在一起看。

常见的错误修复顺序是：先确认 HTTPRoute 的命名空间和 parentRefs，再确认 Gateway 是否允许该 Route 来源，最后在被引用 Service 所在命名空间补上最小 ReferenceGrant。删除授权后，符合 Gateway API 的实现不应继续允许原先被授权的跨命名空间引用。

记住这张最小判断表

• “路由挂不上 Gateway”看 allowedRoutes；
• “后端 Service 解析失败”看目标命名空间的 ReferenceGrant；
• “两层状态都正常仍不通”再进入 Gateway 控制器、Service 端口和端点排查。

ReferenceGrant 之所以存在，不是为了增加一层难记的 YAML，而是把跨命名空间访问变成目标资源所有者可见、可审计、可撤销的授权。把它和 allowedRoutes 分开理解，配置失败时就不会再用“Gateway 已允许跨命名空间”来解释所有问题。

相关问题

ReferenceGrant 应该创建在哪个命名空间？

创建在被引用资源所在的目标命名空间。HTTPRoute 在哪里并不决定授权对象的位置。

allowedRoutes 配置为 All 后还需要 ReferenceGrant 吗？

通常仍需要。All 只扩大 Gateway listener 接受的 Route 来源范围，不会自动授权 Route 读取另一个命名空间的 Service 或 Secret。

ReferenceGrant 能代替 NetworkPolicy 吗？

不能。它表达 Gateway API 资源引用的信任关系，NetworkPolicy 和应用鉴权仍然承担各自的网络与业务访问控制职责。