RoutePolicy

RoutePolicy CRD 提供按路由的 HTTP 流量行为覆盖，将 nginx‑ingress 注解的等价功能引入 Gateway API 模式。它是一个 Gateway API 本地策略，通过 targetRefs 绑定到 HTTPRoute 资源，支持三级继承：命名空间 → 网关 → 路由。

apiVersion: gateway.nantian.dev/v1alpha1
kind: RoutePolicy
metadata:
  name: large-uploads
  namespace: nantian-demo
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: file-upload-route
  default:
    timeout:
      request: 120s
      backendRequest: 90s
      connect: 30s
      nextUpstream: 10s
    bodyLimit:
      maxRequestBodyBytes: 52428800
      requestBodyBufferBytes: 131072
      maxRequestHeaderBytes: 65536
    proxy:
      requestBuffering: true
      responseBuffering: false
      bufferSize: 4096
      bufferCount: 8
    connection:
      keepaliveRequests: 1000
      keepaliveTime: 3600s
      keepaliveTimeout: 75s
      upstreamKeepalivePoolSize: 320
      upstreamKeepaliveIdle: 60s

继承模型

RoutePolicy 使用三级优先级体系。高层级覆盖低层级：

优先级	targetRef	作用域
3（最高）	kind: HTTPRoute	应用到单个 HTTPRoute。
2	kind: Gateway	该网关上所有路由的默认值。
1（最低）	targetRefs: []（空）	策略所在命名空间内所有路由的默认值。

所有字段均为可选。未设置字段会向下级联：如果路由级策略未设置 timeout.connect，则使用网关级的值。如果没有任何策略提供值，则使用数据面全局默认值。

当同一级别的两个策略都指向同一资源时，两者均不生效（该路由回退到下一级）。

目标选择

targetRefs 字段指定策略绑定的资源：

字段	描述
group	目标的 API 组。对于 Gateway 和 HTTPRoute 目标，必须为 gateway.networking.k8s.io。
kind	Gateway 表示网关级默认值，HTTPRoute 表示按路由覆盖。
name	目标资源的名称，必须与策略在同一命名空间中。

将 targetRefs 留空可创建命名空间级默认值。每个命名空间只能有一个命名空间级 RoutePolicy。

策略字段

所有字段均为可选。省略某节表示让下一继承层级或全局默认值生效。

timeout（超时）

覆盖数据面对于目标路由上请求的默认超时设置。

字段	类型	默认值	描述
request	duration	60s	完整请求‑响应周期的最长持续时间。对应 nginx.ingress.kubernetes.io/proxy-read-timeout。
backendRequest	duration	15s	单次后端请求尝试的最长持续时间。对应 nginx.ingress.kubernetes.io/proxy-send-timeout。
connect	duration	5s	与后端建立 TCP 连接的最长持续时间。对应 nginx.ingress.kubernetes.io/proxy-connect-timeout。
nextUpstream	duration	—	重试期间寻找可用上游所花费的最长持续时间。对应 nginx.ingress.kubernetes.io/proxy-next-upstream-timeout。

bodyLimit（请求体限制）

按路由限制请求体和请求头的大小。

字段	类型	默认值	描述
maxRequestBodyBytes	uint64	10485760（10 MiB）	最大请求体大小（字节）。超过此限制的请求会收到 HTTP 413。对应 nginx.ingress.kubernetes.io/proxy-body-size。
requestBodyBufferBytes	uint64	131072（128 KiB）	在写入临时文件之前用于读取请求体的缓冲区大小。对应 nginx.ingress.kubernetes.io/client-body-buffer-size。
maxRequestHeaderBytes	uint64	65536（64 KiB）	所有请求头的最大总大小。对应 nginx.ingress.kubernetes.io/client-header-buffer-size。

proxy（代理缓冲）

控制 HTTP 代理缓冲行为。

字段	类型	默认值	描述
requestBuffering	bool	true	在代理前缓冲完整的客户端请求体。对应 nginx.ingress.kubernetes.io/proxy-request-buffering。
responseBuffering	bool	true	在发送给客户端前缓冲后端响应。对应 nginx.ingress.kubernetes.io/proxy-buffering。
bufferSize	uint64	4096	每个响应缓冲区的大小（字节）。对应 nginx.ingress.kubernetes.io/proxy-buffer-size。
bufferCount	uint32	8	响应缓冲区的数量。对应 nginx.ingress.kubernetes.io/proxy-buffers-number。

connection（连接保持）

控制面向客户端和上游连接的保持活动行为。

字段	类型	默认值	描述
keepaliveRequests	uint32	1000	单个 keepalive 连接上允许的最大请求数。对应 nginx.ingress.kubernetes.io/keepalive-requests。
keepaliveTime	duration	3600s（1 小时）	keepalive 连接的最长生命周期。
keepaliveTimeout	duration	75s	关闭 keepalive 连接前的最长空闲时间。对应 nginx.ingress.kubernetes.io/keepalive-timeout。
upstreamKeepalivePoolSize	uint32	320	维护的空闲上游 keepalive 连接的最大数量。对应 nginx.ingress.kubernetes.io/upstream-keepalive-connections。
upstreamKeepaliveIdle	duration	60s	关闭上游 keepalive 连接前的最长空闲时间。对应 nginx.ingress.kubernetes.io/upstream-keepalive-time。

Nginx Ingress 迁移

如果你正在从 nginx‑ingress 迁移，下表列出了注解与 RoutePolicy 字段的对应关系：

nginx‑ingress 注解	RoutePolicy 字段
nginx.ingress.kubernetes.io/proxy-body-size	default.bodyLimit.maxRequestBodyBytes
nginx.ingress.kubernetes.io/client-body-buffer-size	default.bodyLimit.requestBodyBufferBytes
nginx.ingress.kubernetes.io/client-header-buffer-size	default.bodyLimit.maxRequestHeaderBytes
nginx.ingress.kubernetes.io/proxy-read-timeout	default.timeout.request
nginx.ingress.kubernetes.io/proxy-send-timeout	default.timeout.backendRequest
nginx.ingress.kubernetes.io/proxy-connect-timeout	default.timeout.connect
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout	default.timeout.nextUpstream
nginx.ingress.kubernetes.io/proxy-request-buffering	default.proxy.requestBuffering
nginx.ingress.kubernetes.io/proxy-buffering	default.proxy.responseBuffering
nginx.ingress.kubernetes.io/proxy-buffer-size	default.proxy.bufferSize
nginx.ingress.kubernetes.io/proxy-buffers-number	default.proxy.bufferCount
nginx.ingress.kubernetes.io/keepalive-requests	default.connection.keepaliveRequests
nginx.ingress.kubernetes.io/keepalive-timeout	default.connection.keepaliveTimeout
nginx.ingress.kubernetes.io/upstream-keepalive-connections	default.connection.upstreamKeepalivePoolSize
nginx.ingress.kubernetes.io/upstream-keepalive-time	default.connection.upstreamKeepaliveIdle

示例

按路由超时覆盖

为慢速后端增加请求超时时间：

apiVersion: gateway.nantian.dev/v1alpha1
kind: RoutePolicy
metadata:
  name: slow-backend-timeout
  namespace: default
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: slow-report-route
  default:
    timeout:
      request: 300s

文件上传大小限制

限制特定路由的上传大小：

apiVersion: gateway.nantian.dev/v1alpha1
kind: RoutePolicy
metadata:
  name: upload-limit
  namespace: default
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: upload-route
  default:
    bodyLimit:
      maxRequestBodyBytes: 52428800  # 50 MiB

命名空间级默认值

为命名空间中所有路由设置默认超时：

apiVersion: gateway.nantian.dev/v1alpha1
kind: RoutePolicy
metadata:
  name: ns-defaults
  namespace: team-a
spec:
  default:
    timeout:
      request: 60s
      connect: 10s
    connection:
      keepaliveRequests: 500