配置 GatewayAPI 路由

前提条件

请确保您已阅读安装文档后再继续操作。

通过 Web 控制台配置

  1. 进入 Alauda Container Platform -> Networking -> Routes
  2. 点击 Create Route 按钮

创建 HTTPRoute

字段说明YAML 路径
Publish to Listener发布到监听器.spec.parentRefs
Hostnames主机名.spec.hostnames
Matches匹配规则.spec.rules[].matches
Filters过滤器.spec.rules[].filters
Backend Instance后端.spec.rules[].backendRefs
Session Affinity会话亲和.spec.rules[].sessionPersistence

创建 TCP/UDP 路由

字段说明YAML 路径
Publish to Listener发布到监听器.spec.parentRefs
Backend Instance后端.spec.rules[].backendRefs

通过 YAML 配置

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: demo-443
  namespace: demo
spec:
  hostnames:
    - example.com
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: https
  rules:
    - backendRefs:
        - group: ''
          kind: Service
          name: echo-resty
          namespace: demo-space
          port: 80
          weight: 100
      filters: [] 
      matches:
        - path:
            type: Exact
            value: /a
      sessionPersistence:
        type: Cookie
        sessionName: a
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: tcp
  namespace: demo-space
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: tcp
  rules:
    - backendRefs:
        - group: ''
          kind: Service
          name: echo-resty
          port: 80
          weight: 100
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: UDPRoute
metadata:
  name: udp
  namespace: demo
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      namespace: demo
      sectionName: udp
  rules:
    - backendRefs:
        - group: ''
          kind: Service
          name: echo-resty
          namespace: demo
          port: 53
          weight: 100

介绍

每个路由都是由 GatewayAPI 规范定义的 CR。有关每种路由类型的字段和配置选项的详细信息,请参阅官方文档:

主机名

Route 中的 hostnames 字段是字符串数组。 它遵循主机名交集规则

发布到监听器

规则

每个路由可以包含多个规则。每条规则由以下组件组成:

匹配

定义请求被该规则路由所需满足的条件。

一条规则可以有多个匹配:

  • 每个匹配由多个条件组成(例如路径、头部、查询参数、方法)
  • 匹配内的条件使用 AND 逻辑(全部满足)
  • 匹配之间使用 OR 逻辑(任一匹配满足即可)

示例:如果匹配1要求 path=/apiheader=v1,匹配2要求 query=test,则请求满足 (path=/api 且 header=v1)(query=test) 中任意一项即被路由。

匹配条件类型
对象方法值类型说明值要求
Path
Exact路径(字符串)精确匹配 URL 路径且区分大小写。即对 /abc 的精确匹配只匹配 /abc,不匹配 /abc/、/Abc 或 /abcd。必须以 / 开头,不允许连续 //
PathPrefix路径(字符串)基于以 / 分割的 URL 路径前缀匹配。匹配区分大小写,且按路径元素逐级匹配。例如,路径 /abc、/abc/ 和 /abc/def 都匹配前缀 /abc,但路径 /abcd 不匹配。必须以 / 开头,不允许连续 //
RegularExpression路径(字符串)正则表达式引擎:RE2。例如 /api/v1/.*
Header
Exact名称(头部键)+值精确匹配头部值。
RegularExpression名称(头部键)+值正则表达式引擎:RE2。
QueryParam
Exact名称(参数键)+值精确匹配查询参数值。参数值长度:1-1024 字符
RegularExpression名称(参数键)+值正则表达式引擎:RE2。
Method-方法名称HTTP 方法匹配。GETHEADPOSTPUTDELETECONNECTOPTIONSTRACEPATCH
匹配条件参考
条件类型官方文档链接
PathHTTPPathMatch
HeadersHTTPHeaderMatch
QueryParamsHTTPQueryParamMatch
MethodHTTPMethod

过滤器

指定对请求/响应进行的转换或修改。

过滤器类型
类型方法值类型说明值要求
RequestHeaderModifierSet名称(字符串)+值(字符串)覆盖请求头指定名称和值最多16项,值长度:1-4096 字符
Add名称(字符串)+值(字符串)向请求头添加,追加到已有值最多16项,值长度:1-4096 字符
Remove[]string从请求头移除指定头部(不区分大小写)最多16项
ResponseHeaderModifierSet名称(字符串)+值(字符串)覆盖响应头指定名称和值最多16项,值长度:1-4096 字符
Add名称(字符串)+值(字符串)向响应头添加,追加到已有值最多16项,值长度:1-4096 字符
Remove[]string从响应头移除指定头部(不区分大小写)最多16项
RequestRedirectScheme字符串Location 头的协议(http/https)可选,枚举:http | https
HostnamePreciseHostnameLocation 头的主机名可选
ReplaceFullPath字符串替换整个请求路径可选,最大1024字符
ReplacePrefixMatch字符串替换匹配的路径前缀可选,最大1024字符,仅支持 PathPrefix 匹配
PortPortNumberLocation 头的端口号可选,范围:1-65535
StatusCode整数HTTP 重定向状态码可选,默认:302,枚举:301 | 302
URLRewriteHostnamePreciseHostname请求中重写的主机名可选
ReplaceFullPath字符串替换整个请求路径可选,最大1024字符
ReplacePrefixMatch字符串替换匹配的路径前缀可选,最大1024字符,仅支持 PathPrefix 匹配
CORSAllowOrigins[]stringCORS 请求允许的来源列表可选
AllowMethods[]HTTPMethod允许的 HTTP 方法列表可选,例如 GET、POST、PUT
AllowHeaders[]stringCORS 请求允许的头部列表可选
ExposeHeaders[]string响应中暴露给客户端的头部列表可选
MaxAgeDurationCORS 预检请求的缓存时间可选
AllowCredentialsbool是否允许 CORS 请求携带凭证可选

注意

  • RequestRedirectURLRewrite 不能在同一规则中同时使用
  • ReplacePrefixMatch 仅兼容 PathPrefix 类型的 HTTPRouteMatch
  • 头部名称根据 RFC 7230 不区分大小写
  • 同一头部的多个值必须使用 RFC 7230 逗号分隔格式
过滤器参考
过滤器类型官方文档链接
RequestHeaderModifierHTTPHeaderFilter
ResponseHeaderModifierHTTPHeaderFilter
RequestRedirectHTTPRequestRedirectFilter
URLRewriteHTTPURLRewriteFilter
CORSHTTPCORSFilter
RequestMirrorHTTPRequestMirrorFilter
HTTPExternalAuthFilterHTTPExternalAuthFilter

后端

定义匹配请求应转发到的目标服务。

每个服务可以设置 weight 字段,用于指定流量分配比例。

高级 HTTPRoute 规则设置

HTTPRoute 规则支持额外的配置字段,如重试策略、超时及其他流量管理参数。

超时
字段规范说明
.spec.rules[].timeoutsHTTPRouteTimeouts
重试
字段规范说明
.spec.rules[].retryHTTPRouteRetry
会话亲和

配置会话亲和设置,确保来自同一客户端的请求被路由到相同后端。

字段规范说明
.spec.rules[].sessionPersistenceSessionPersistence

下一步

Envoy Gateway 任务

相关任务