# 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主要参数说明
表1HTTPRouteSpec 
| 参数          | 是否必填 | 参数类型                                                               | 描述                                                                                            |
|:---|:---|:---|:---|
| 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  | 路由规则列表。                                                                                      |
   
 表2ParentReference 
| 参数         | 是否必填 | 参数类型      | 描述                                                                                                                    |
|:---|:---|:---|:---|
| 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。                                                                                              |
   
![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/note_3.0-zh-cn.png)
**监听器缺省关联规则** ： 当sectionName和port**均未填写**时，关联逻辑如下：
- **Kind = Gateway**：默认关联该Gateway及其所属ListenerSet下的所有监听器。
- **Kind = ListenerSet**：默认关联该ListenerSet下的所有监听器。
 
 表3HTTPRouteRule 
| 参数         | 是否必填 | 参数类型                                                                    | 描述                                                                                                                        |
|:---|:---|:---|:---|
| 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。                                                                  |
   
 表4HTTPRouteMatch 
| 参数            | 是否必填 | 参数类型                                                                      | 描述                                                                                        |
|:---|:---|:---|:---|
| 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支持 |
   
 表5HTTPPathMatch 
| 参数      | 是否必填 | 参数类型   | 描述                                                                                               |
|:---|:---|:---|:---|
| type | 否  | String  | 匹配类型，默认PathPrefix。 取值：Exact（精确）、PathPrefix（前缀）、RegularExpression（正则） |
| value | 否    | String | 匹配路径值，默认 /。 Exact/PathPrefix须以 / 开头，不得含 //、/./、/../ 等。               |
   
 表6HTTPHeaderMatch 
| 参数   | 是否必填 | 参数类型    | 描述                                                                                                                                                                                                                                                                                                  |
|:---|:---|:---|:---|
| type  | 否      | String | 匹配类型，默认Exact。 取值范围：Exact                                                                                                                                                                                                                                           |
| name  | 是   | String  | HTTP头名称，大小写不敏感。                                                                                                                                                                                                                                                                                       |
| value | 是     | String  | HTTP头匹配值。长度1-4096。支持以下两种配置形式： - 单值匹配：填写单个字符串值（如 "prod"），请求头的值与该值完全匹配。  - 多值（OR）匹配：以JSON数组序列化字符串格式填写（如 \["prod","stage"\]），匹配数组中的任意一个值即可。   |
   
 表7HTTPQueryParamMatch 
| 参数    | 是否必填 | 参数类型   | 描述                                                                                                                                                                                                                                                                                            |
|:---|:---|:---|:---|
| type   | 否      | String | 匹配类型，默认Exact。 取值范围：Exact                                                                                                                                                                                                                                         |
| name   | 是   | String  | 查询参数名，精确匹配。                                                                                                                                                                                                                                                                                  |
| value | 是  | String   | 查询参数值，长度1-1024。支持以下两种配置形式： - 单值匹配：直接填写单个字符串值（如 "v1"），查询参数值与该值匹配。  - 多值（OR）匹配：以JSON数组序列化字符串格式填写（如 \["v1","v2"\]），匹配数组中的任意一个值即可。   |
   
 表8HTTPBackendRef 
| 参数      | 是否必填 | 参数类型    | 描述                             |
|:---|:---|:---|:---|
| 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表示不转发流量。          |
   
 表9HTTPRouteFilter 
| 参数                    | 是否必填    | 参数类型                                                                | 描述                                                                                                                                                                                                                                                                                                                             |
|:---|:---|:---|:---|
| type                   | 是    | String                                                              | 过滤器类型。 - RequestHeaderModifier：修改请求头（添加请求头、删除请求头）。  - RequestRedirect：请求重定向。  - URLRewrite：URL重写。   |
| requestHeaderModifier | 条件必填  | [HTTPHeaderFilter] object           | type为RequestHeaderModifier时必填。支持Add和Remove，不支持Set。                                                                                                                                                                                                                                                                              |
| requestRedirect       | 条件必填  | [HTTPRequestRedirectFilter] object | type为RequestRedirect时必填。                                                                                                                                                                                                                                                                                                        |
| urlRewrite            | 条件必填 | [HTTPURLRewriteFilter] object      | type为URLRewrite时必填。                                                                                                                                                                                                                                                                                                             |
   
 表10HTTPHeaderFilter 
| 参数       | 是否必填 | 参数类型            | 描述                                       |
|:---|:---|:---|:---|
| add     | 否   | Array of objects | 追加请求头。映射为InsertHeaders(USER_DEFINED)。 |
| remove | 否    | Array of strings | 移除请求头名称列表。                              |
   
 表11HTTPRequestRedirectFilter 
| 参数          | 是否必填 | 参数类型                                                       | 描述                                    |
|:---|:---|:---|:---|
| scheme      | 否    | String                                                       | 重定向协议，取值http、https。不填则沿用请求协议。          |
| hostname    | 否   | String                                                       | 重定向主机名，不填则沿用请求Host。                 |
| path       | 否   | [HTTPPathModifier] object | 路径修改配置。                               |
| port       | 否  | Integer                                                     | 重定向端口，范围1-65535。不填时根据scheme推导。     |
| statusCode | 否   | Integer                                                      | 重定向状态码，默认302。取值301/302/303/307/308。 |
   
 表12HTTPURLRewriteFilter 
| 参数       | 是否必填 | 参数类型                                                        | 描述                       |
|:---|:---|:---|:---|
| hostname | 否     | String                                                      | 转发时替换的Host头值。            |
| path     | 否   | [HTTPPathModifier] object | 路径重写配置。仅支持ReplaceFullPath。 |
   
 表13HTTPPathModifier（Redirect/Rewrite共用） 
| 参数           | 是否必填  | 参数类型    | 描述                                                                      |
|:---|:---|:---|:---|
| type         | 是    | String | 修改类型：ReplaceFullPath（全路径替换）、ReplacePrefixMatch（前缀替换，须配合PathPrefix match） |
| replaceFullPath | 条件必填 | String  | type为ReplaceFullPath时必填。                                                |