文档首页/ 云容器引擎 CCE/ 用户指南/ 网络/ 网关API（Gateway API）/ ELB Gateway/ HTTPRoute参数配置

更新时间：2026-11-10 GMT+08:00

HTTPRoute参数配置

在ELB Gateway架构中，HTTPRoute用于将客户端的HTTP/HTTPS请求映射并分发到特定的后端Service。通过配置路由规则（Rules），可以实现基于域名、路径、请求头等的流量路由以及重定向和请求改写等高级功能。

前提条件

集群版本已支持ELB Gateway功能。
已创建可用的Gateway实例。
已配置好对应的后端Service及相关业务Pod。

约束与限制

CCE Turbo集群的独享型可以选择ClusterIP或NodePort类型的Service，其他的只能选择NodePort类型。

HTTPRoute配置指导

基础转发

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: route-basic
  namespace: default
spec:
  parentRefs:                              # 关联的 Gateway
    - name: demo-gateway
  hostnames:                                # 域名
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix               # 匹配类型: Exact 精准匹配 | PathPrefix 前缀匹配 | RegularExpression 正则匹配
            value: /api/v1                 # 匹配路径
      backendRefs:                        
        - name: backend-service            # 后端 Service 名称
          port: 8080                       # 后端 Service 端口

Header匹配转发

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: route-header
  namespace: default
spec:
  parentRefs:
    - name: demo-gateway
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
          headers:                         # 请求头匹配，翻译为单个 HEADER 规则
            - type: Exact                  # 匹配类型: Exact 精准匹配
              name: x-env                  # 请求头名称 
              value: '["v1","v2"]'         # 请求头值，匹配v1或v2
      backendRefs:
        - name: backend-service
          port: 8080

Query参数匹配转发

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: route-query
  namespace: default
spec:
  parentRefs:
    - name: demo-gateway
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /search
          queryParams:                     # Query 参数匹配
            - type: Exact                   # 匹配类型: Exact 精准匹配
              name: version                # 参数名
              value: '["v1","v2"]'         # 参数值，匹配v1或v2
      backendRefs:
        - name: backend-service
          port: 8080

URL重写、请求头增删

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: basic-route
  namespace: default
spec:
  parentRefs:
    - name: demo-gateway
      sectionName: http-listener
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1
      filters:
        # URL 重写
        - type: URLRewrite                 # 不改变 action，附加 RewriteUrlConfig
          urlRewrite:
            hostname: backend.internal.example.com  # 重写 Host
            path:                           # 重写路径
              type: ReplaceFullPath         # 仅支持 ReplaceFullPath
              replaceFullPath: /v1/api      # 替换后的完整路径
        # 请求头修改
        - type: RequestHeaderModifier       # 附加 InsertHeaders / RemoveHeaders
          requestHeaderModifier:
            add:                             # 添加请求头，映射为 InsertHeaders (USER_DEFINED)
              - name: my-header
                value: "true"
            remove:                           # 删除请求头，映射为 RemoveHeadersConfig
              - x-request-id                 # 需删除的请求头名称
      backendRefs:
        - name: backend-service
          port: 8080

请求重定向（RequestRedirect）

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: route-redirect
  namespace: default
spec:
  parentRefs:
    - name: demo-gateway
  hostnames:
    - "old.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /old-path
      filters:
        - type: RequestRedirect             # 触发 REDIRECT_TO_URL action，不再走 backendRefs
          requestRedirect:
            scheme: https                   # 重定向协议
            hostname: new.example.com       # 重定向域名
            port: 443                       # 重定向端口
            path:                           # 重定向路径
              type: ReplaceFullPath         # 仅支持 ReplaceFullPath
              replaceFullPath: /new-path    # 替换后的完整路径
            statusCode: 301                 # HTTP 状态码，默认 302

多后端加权分发（仅独享型ELB支持）

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: weighted-route
  namespace: default
spec:
  parentRefs:
    - name: demo-gateway
  hostnames:
    - "canary.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: backend-v1
          port: 8080
          weight: 90        # 90% 流量
        - name: backend-v2
          port: 8080
          weight: 10        # 10% 流量（金丝雀发布）

HTTPRoute配置多个转发规则

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: route-basic
  namespace: default
spec:
  parentRefs:                              # 关联的 Gateway
    - name: demo-gateway
  hostnames:                                # 域名
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix               # 匹配类型: Exact 精准匹配 | PathPrefix 前缀匹配 | RegularExpression 正则匹配
            value: /api/v1                 # 匹配路径
      backendRefs:                        
        - name: backend-service            # 后端 Service 名称
          port: 8080                       # 后端 Service 端口
    - matches:
        - path:
            type: PathPrefix               # 匹配类型: Exact 精准匹配 | PathPrefix 前缀匹配 | RegularExpression 正则匹配
            value: /api/v2                 # 匹配路径
      backendRefs:                        
        - name: backend-service2            # 后端 Service 名称
          port: 8080                       # 后端 Service 端口

HTTPRoute主要参数说明

表1 HTTPRouteSpec
参数	是否必填	参数类型	描述
parentRefs	是	Array of ParentReference objects	父级 Gateway 引用列表，最多 32 项。默认关联到 gateway.networking.k8s.io/Gateway。引用同一父对象时 sectionName/port 须唯一。
hostnames	否	Array of strings	匹配 HTTP Host 头列表。支持精确和 *.example.com 通配。不填则匹配所有。
rules	否	Array of HTTPRouteRule objects	路由规则列表。

表2 ParentReference
参数	是否必填	参数类型	描述
group	否	String	父资源API组（Group）。默认值：gateway.networking.k8s.io
kind	否	String	父资源类型（Kind）。可选值：Gateway、ListenerSet 默认值：Gateway
namespace	否	String	父资源所在的命名空间。不填时默认与当前Route在同一命名空间。若跨命名空间引用，须满足目标Gateway或ListenerSet配置的allowedRoutes允许规则。
name	是	String	父资源名称。
sectionName	否	String	目标Gateway或ListenerSet中的Listener（监听器）名称。
port	否	Integer	目标监听端口，取值范围：1 - 65535。

监听器缺省关联规则：当sectionName和port均未填写时，关联逻辑如下：

Kind = Gateway：默认关联该Gateway及其所属ListenerSet下的所有监听器。
Kind = ListenerSet：默认关联该ListenerSet下的所有监听器。

表3 HTTPRouteRule
参数	是否必填	参数类型	描述
name	否	String	规则名称，同一Route内唯一。
matches	否	Array of HTTPRouteMatch objects	匹配条件列表。各match之间为OR关系，match内各字段为AND。不填默认 / 前缀匹配。
filters	否	Array of HTTPRouteFilter objects	过滤器列表。RequestRedirect与URLRewrite不可同时使用。实际支持：RequestRedirect、URLRewrite、RequestHeaderModifier
backendRefs	否	Array of HTTPBackendRef objects	后端引用列表，最多5项。当filters仅含RequestRedirect时不可同时指定backendRefs。

表4 HTTPRouteMatch
参数	是否必填	参数类型	描述
path	否	HTTPPathMatch object	路径匹配器，默认 {type: PathPrefix, value: "/"}
headers	否	Array of HTTPHeaderMatch objects	请求头匹配器，按name去重。各条件之间为AND。
queryParams	否	Array of HTTPQueryParamMatch objects	查询参数匹配器，按name去重。各条件之间为AND。
method	否	String	HTTP方法匹配。取值GET/HEAD/POST/PUT/DELETE/OPTIONS/PATCH。仅独享型ELB支持

表5 HTTPPathMatch
参数	是否必填	参数类型	描述
type	否	String	匹配类型，默认PathPrefix。取值：Exact（精确）、PathPrefix（前缀）、RegularExpression（正则）
value	否	String	匹配路径值，默认 /。 Exact/PathPrefix须以 / 开头，不得含 //、/./、/../ 等。

表6 HTTPHeaderMatch
参数	是否必填	参数类型	描述
type	否	String	匹配类型，默认Exact。取值范围：Exact
name	是	String	HTTP头名称，大小写不敏感。
value	是	String	HTTP头匹配值。长度1-4096。支持以下两种配置形式：单值匹配：填写单个字符串值（如 "prod"），请求头的值与该值完全匹配。多值（OR）匹配：以JSON数组序列化字符串格式填写（如 ["prod","stage"]），匹配数组中的任意一个值即可。

表7 HTTPQueryParamMatch
参数	是否必填	参数类型	描述
type	否	String	匹配类型，默认Exact。取值范围：Exact
name	是	String	查询参数名，精确匹配。
value	是	String	查询参数值，长度1-1024。支持以下两种配置形式：单值匹配：直接填写单个字符串值（如 "v1"），查询参数值与该值匹配。多值（OR）匹配：以JSON数组序列化字符串格式填写（如 ["v1","v2"]），匹配数组中的任意一个值即可。

表8 HTTPBackendRef
参数	是否必填	参数类型	描述
group	否	String	后端Group，默认""（core API）。
kind	否	String	后端Kind，默认Service。
name	是	String	后端资源名称。
namespace	否	String	后端命名空间，不填则默认Route同命名空间，不支持跨命名空间。
port	条件必填	Integer	目标端口，范围1-65535。引用Service时必填。
weight	否	Integer	权重，默认1，范围0-100。0表示不转发流量。

表9 HTTPRouteFilter
参数	是否必填	参数类型	描述
type	是	String	过滤器类型。 RequestHeaderModifier：修改请求头（添加请求头、删除请求头）。 RequestRedirect：请求重定向。 URLRewrite：URL重写。
requestHeaderModifier	条件必填	HTTPHeaderFilter object	type为RequestHeaderModifier时必填。支持Add和Remove，不支持Set。
requestRedirect	条件必填	HTTPRequestRedirectFilter object	type为RequestRedirect时必填。
urlRewrite	条件必填	HTTPURLRewriteFilter object	type为URLRewrite时必填。

**表10** HTTPHeaderFilter
参数	是否必填	参数类型	描述
add	否	Array of objects	追加请求头。映射为InsertHeaders(USER_DEFINED)。
remove	否	Array of strings	移除请求头名称列表。

**表11** HTTPRequestRedirectFilter
参数	是否必填	参数类型	描述
scheme	否	String	重定向协议，取值http、https。不填则沿用请求协议。
hostname	否	String	重定向主机名，不填则沿用请求Host。
path	否	HTTPPathModifier object	路径修改配置。
port	否	Integer	重定向端口，范围1-65535。不填时根据scheme推导。
statusCode	否	Integer	重定向状态码，默认302。取值301/302/303/307/308。

**表12** HTTPURLRewriteFilter
参数	是否必填	参数类型	描述
hostname	否	String	转发时替换的Host头值。
path	否	HTTPPathModifier object	路径重写配置。仅支持ReplaceFullPath。

**表13** HTTPPathModifier（Redirect/Rewrite共用）
参数	是否必填	参数类型	描述
type	是	String	修改类型：ReplaceFullPath（全路径替换）、ReplacePrefixMatch（前缀替换，须配合PathPrefix match）
replaceFullPath	条件必填	String	type为ReplaceFullPath时必填。

父主题： ELB Gateway

上一篇：Gateway与ListenerSet参数配置

下一篇：自动创建负载均衡配置（lbconfig）