Envoy Gateway 中的 HTTP URL 重写功能详解

Envoy Gateway 中的 HTTP URL 重写功能详解

gateway Manages Envoy Proxy as a Standalone or Kubernetes-based Application Gateway 项目地址: https://gitcode.com/gh_mirrors/gate/gateway

什么是 HTTP URL 重写

HTTP URL 重写是一种在请求转发过程中修改请求 URL 或主机名的功能。在 Envoy Gateway 项目中，这通过 HTTPURLRewriteFilter 过滤器实现，允许开发者在请求到达后端服务前对路径或主机名进行修改。

核心功能特性

Envoy Gateway 的 URL 重写功能提供三种主要操作模式：

1. 前缀路径重写：替换 URL 路径中的前缀部分
2. 完整路径重写：完全替换整个 URL 路径
3. 主机名重写：修改请求的 Host 头信息

使用场景与限制

URL 重写功能特别适用于以下场景：

• 统一 API 入口路径
• 版本化 API 的平滑迁移
• 多环境路由的统一管理
• 后端服务重构时的兼容性保障

需要注意的是：

• 每个路由规则最多只能使用一个 URL 重写过滤器
• 不能与 HTTPRequestRedirect 过滤器同时使用在同一个路由规则上

具体配置示例

1. 前缀路径重写配置

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http-prefix-rewrite
spec:
  parentRefs:
    - name: eg
  hostnames:
    - rewrite.example
  rules:
    - matches:
      - path:
          value: "/old-prefix"
      filters:
      - type: URLRewrite
        urlRewrite:
          path:
            type: ReplacePrefixMatch
            replacePrefixMatch: /new-prefix
      backendRefs:
      - name: backend-service
        port: 8080

此配置将所有以 /old-prefix 开头的请求路径重写为以 /new-prefix 开头，例如：

• /old-prefix/resource → /new-prefix/resource
• 原始路径会保留在 X-Envoy-Original-Path 头中

2. 完整路径重写配置

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http-fullpath-rewrite
spec:
  parentRefs:
    - name: eg
  hostnames:
    - rewrite.example
  rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/legacy/api"
      filters:
      - type: URLRewrite
        urlRewrite:
          path:
            type: ReplaceFullPath
            replaceFullPath: /modern/api/v2
      backendRefs:
      - name: backend-service
        port: 8080

此配置将所有匹配 /legacy/api 前缀的请求路径完全替换为 /modern/api/v2，无论原始路径多长。

3. 主机名重写配置

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http-host-rewrite
spec:
  parentRefs:
    - name: eg
  hostnames:
    - external.example
  rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      filters:
      - type: URLRewrite
        urlRewrite:
          hostname: "internal.service.local"
      backendRefs:
      - name: backend-service
        port: 8080

此配置将保留客户端原始 Host 头在 X-Forwarded-Host 中，但实际转发给后端的 Host 头会被替换为 internal.service.local。

实际效果验证

配置生效后，可以通过以下方式验证：

1. 检查 HTTPRoute 状态：

kubectl get httproute/<route-name> -o yaml

2. 使用 curl 测试：

curl -v --header "Host: rewrite.example" "http://${GATEWAY_HOST}/old-prefix/resource"

在响应中可以看到：

• 实际访问的路径或主机名
• 原始路径保留在 X-Envoy-Original-Path 头中
• 原始主机名保留在 X-Forwarded-Host 头中

最佳实践建议

1. 版本控制：在 API 演进时使用路径重写保持向后兼容
2. 环境隔离：不同环境使用不同的路径前缀但指向相同后端
3. 监控配置：记录原始路径有助于问题排查和流量分析
4. 性能考虑：复杂的重写规则可能影响网关性能，应适度使用

通过合理使用 Envoy Gateway 的 URL 重写功能，可以实现灵活的流量管理策略，同时保持客户端调用的稳定性。

gateway Manages Envoy Proxy as a Standalone or Kubernetes-based Application Gateway 项目地址: https://gitcode.com/gh_mirrors/gate/gateway