配置 GatewayAPI Route

概述

本文档说明在 Gateway 准备就绪后如何配置 Route 资源。Route 会附加到一个或多个 gateway 监听器，并定义匹配流量如何转发到后端服务。

在推荐的工作流程中，本文档位于 Configure GatewayAPI Gateway 之后、Configure GatewayAPI Policy 之前。

除创建和更新操作外，本文档还介绍了 ACP Web Console 提供的额外 route 查看能力。

前提条件

在继续之前，请确保已完成以下步骤：

阅读 Configure GatewayAPI Gateway，了解监听器、附加规则和 EnvoyProxy
创建一个 Route 要附加到的 Gateway

NOTE

本文档先分别介绍每种 route 类型，然后提供 YAML 示例，最后在共享参考部分解释通用的 route 概念。

配置

Route 会附加到 Gateway 上的一个或多个监听器。可选择的监听器取决于 route 类型、监听器协议以及监听器允许的 route 命名空间设置。

通过 Web Console 配置

导航到 Alauda Container Platform -> Networking -> Gateway -> Routes
单击 Create Route 按钮
选择 route 类型（HTTPRoute、TCPRoute、UDPRoute、GRPCRoute 或 TLSRoute）

创建 HTTPRoute

字段	描述	YAML 路径
发布到监听器	publish to listener	`.spec.parentRefs`
Hostnames	hostnames	`.spec.hostnames`
Matches	matches	`.spec.rules[].matches`
Filters	filters	`.spec.rules[].filters`
Backend 实例	backend	`.spec.rules[].backendRefs`
Options	options	`.spec.rules[].filters`, `.spec.rules[].timeouts`, `.spec.rules[].retry`, `.spec.rules[].sessionPersistence`

Options 配置

Options 字段允许你配置高级流量管理设置：

选项	描述	YAML 路径
会话亲和性	session persistence	`.spec.rules[].sessionPersistence`
超时	timeout settings	`.spec.rules[].timeouts`
重试	retry policy	`.spec.rules[].retry`

创建 TCP/UDP Route

字段	描述	YAML 路径
发布到监听器	publish to listener	`.spec.parentRefs`
Backend 实例	backend	`.spec.rules[].backendRefs`

创建 GRPCRoute

字段	描述	YAML 路径
发布到监听器	publish to listener	`.spec.parentRefs`
Hostnames	hostnames	`.spec.hostnames`
Matches	grpc matches	`.spec.rules[].matches`
Filters	grpc filters	`.spec.rules[].filters`
Backend 实例	backend	`.spec.rules[].backendRefs`

创建 TLSRoute

字段	描述	YAML 路径
发布到监听器	publish to listener	`.spec.parentRefs`
Hostnames	hostnames（可选）	`.spec.hostnames`
Backend 实例	backend	`.spec.rules[].backendRefs`

通过 YAML 配置

以下最小示例创建一个 HTTPRoute，它附加到 demo Gateway 的 https 监听器，并将匹配到的流量转发到后端 Service。

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:
    - matches:
        - path:
            type: Exact
            value: /a
      backendRefs:
        - group: ''
          kind: Service
          name: echo-resty
          namespace: demo-space
          port: 80
          weight: 100

如果你需要更多 route 类型和高级 HTTPRoute 选项，请使用以下完整示例：

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
      timeouts:
        request: '30s'
        backendRequest: '10s'
      retry:
        codes:
          - 503
        attempts: 3
        backoff: '100ms'
      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
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: grpc
  namespace: demo
spec:
  hostnames:
    - grpc.example.com
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: https
  rules:
    - matches:
        - method:
            type: service
            value: myservice
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            set:
              - name: x-custom-header
                value: custom-value
      backendRefs:
        - group: ''
          kind: Service
          name: grpc-service
          port: 50051
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: tls
  namespace: demo
spec:
  hostnames:
    - tls.example.com
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: tls
  rules:
    - backendRefs:
        - group: ''
          kind: Service
          name: tls-backend
          port: 443

Hostnames
Publish to listener
Rules
Backend
Filters
Matches
Options
Timeout
Retry
Session Persistence

Route 字段参考

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

发布到监听器

在 Web Console 中

在 Web Console 中，你可以选择多个监听器来发布 route。可用的监听器候选项会根据以下条件进行过滤：

用户权限：你必须有权访问 gateway 的命名空间（项目必须包含该命名空间）。
Route 命名空间 allowlist：gateway 监听器允许的 route 命名空间必须包含 route 的命名空间。
Route kind 匹配：route 的 kind（HTTPRoute、GRPCRoute 等）必须与监听器允许的 route kinds 匹配。

对于更复杂的跨命名空间场景，请参阅附加到在其他命名空间中创建的 gateway。

在 YAML 中

sectionName 是监听器名称。
Route 只能附加到支持其特定 kind 的监听器。
默认情况下，route 只能附加到 Gateway 位于同一命名空间的监听器。

对于跨命名空间附加，请参阅附加到在其他命名空间中创建的 gateway。

Backend

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

每个 service 都可以有一个 weight 字段，用于指定路由到该 service 的流量比例。

Hostnames

hostnames 字段受 HTTPRoute、GRPCRoute 和 TLSRoute 支持。TCPRoute 和 UDPRoute 不使用此字段。

hostnames 是一个字符串数组。它遵循 Hostname Intersection Rules。

Rules

每个 route 可以包含多个规则。每个规则由以下组件组成：

Matches

定义请求必须满足的条件，才能由该规则路由。

一个规则可以有多个 match：

每个 match 由多个条件组成（例如 path、headers、query parameters、method）
match 内部的条件使用 AND 逻辑（必须全部满足）
match 之间使用 OR 逻辑（任意一个 match 即可满足规则）

示例：如果 Match-1 要求 path=/api AND header=v1，而 Match-2 要求 query=test，那么当请求满足 (path=/api AND header=v1) OR (query=test) 时会被路由。

match 结构在不同 route 类型之间是通用的，但支持的 match 条件取决于 route 类型。例如，HTTPRoute 和 GRPCRoute 支持不同的 match 条件集合。

Filters

指定要应用于请求或响应的转换或修改。

filter 概念在不同 route 类型之间是通用的，但支持的 filter 类型取决于 route 类型。

HTTPRoute 参考

以下 match 条件、filter 类型和高级选项用于 HTTPRoute。

Match Condition Types

对象	方法	值类型	描述	值要求
Path
	`Exact`	path (string)	精确匹配 URL path，且区分大小写。这意味着对 /abc 的精确 path 匹配只会匹配到 /abc，不会匹配 /abc/、/Abc 或 /abcd。	必须以 `/` 开头，不能出现连续的 `//`。
	`PathPrefix`	path (string)	基于按 `/` 分隔的 URL path 前缀进行匹配。匹配区分大小写，并且按逐个 path element 的方式进行。例如，/abc、/abc/ 和 /abc/def 都会匹配前缀 /abc，但 /abcd 不会。	必须以 `/` 开头，不能出现连续的 `//`。
	`RegularExpression`	path (string)	正则引擎：RE2。	例如，`/api/v1/.*`。
Header
	`Exact`	name (header key) + value	精确匹配 header 值。
	`RegularExpression`	name (header key) + value	正则引擎：RE2。
QueryParam
	`Exact`	name (param key) + value	精确匹配 query parameter 值。	参数值：1-1024 个字符
	`RegularExpression`	name (param key) + value	正则引擎：RE2。
Method	-	method name	HTTP method 匹配。	`GET`、`HEAD`、`POST`、`PUT`、`DELETE`、`CONNECT`、`OPTIONS`、`TRACE`、`PATCH`

Match Condition References

条件类型	官方文档
Path	HTTPPathMatch
Headers	HTTPHeaderMatch
QueryParams	HTTPQueryParamMatch
Method	HTTPMethod

Filter Types

类型	方法	值类型	描述	值要求
RequestHeaderModifier	`Set`	name (string) + value (string)	使用给定的名称和值覆盖 request header	最多 16 项，值：1-4096 个字符
	`Add`	name (string) + value (string)	向 request 添加 header，并追加到现有值	最多 16 项，值：1-4096 个字符
	`Remove`	[]string	从 request 中移除指定的 headers（不区分大小写）	最多 16 项
ResponseHeaderModifier	`Set`	name (string) + value (string)	使用给定的名称和值覆盖 response header	最多 16 项，值：1-4096 个字符
	`Add`	name (string) + value (string)	向 response 添加 header，并追加到现有值	最多 16 项，值：1-4096 个字符
	`Remove`	[]string	从 response 中移除指定的 headers（不区分大小写）	最多 16 项
RequestRedirect	`Scheme`	string	Location header 的 scheme（http/https）	可选，枚举：`http`\|`https`
	`Hostname`	PreciseHostname	Location header 的 hostname	可选
	`ReplaceFullPath`	string	替换整个 request path	可选，最多 1024 个字符
	`ReplacePrefixMatch`	string	替换匹配到的 path 前缀	可选，最多 1024 个字符，仅可与 `PathPrefix` match 一起使用
	`Port`	PortNumber	Location header 的端口	可选，范围：1-65535
	`StatusCode`	int	HTTP 重定向状态码	可选，默认值：302，枚举：`301`\|`302`
URLRewrite	`Hostname`	PreciseHostname	要在 request 中重写的 hostname	可选
	`ReplaceFullPath`	string	替换整个 request path	可选，最多 1024 个字符
	`ReplacePrefixMatch`	string	替换匹配到的 path 前缀	可选，最多 1024 个字符，仅可与 `PathPrefix` match 一起使用
CORS	`AllowOrigins`	[]string	CORS 请求允许的 origin 列表	可选
	`AllowMethods`	[]HTTPMethod	允许的 HTTP methods 列表	可选，例如 GET、POST、PUT
	`AllowHeaders`	[]string	CORS 请求允许的 headers 列表	可选
	`ExposeHeaders`	[]string	在响应中暴露给客户端的 headers 列表	可选
	`MaxAge`	Duration	CORS 预检响应的缓存时长	可选
	`AllowCredentials`	bool	是否允许 CORS 请求携带凭据	可选

注意：

RequestRedirect 和 URLRewrite 不能在同一个 rule 中一起使用
ReplacePrefixMatch 仅与 PathPrefix HTTPRouteMatch 兼容
根据 RFC 7230，header 名称不区分大小写
同一 header 的多个值必须使用 RFC 7230 以逗号分隔的格式

Filter References

Filter 类型	官方文档
RequestHeaderModifier	HTTPHeaderFilter
ResponseHeaderModifier	HTTPHeaderFilter
RequestRedirect	HTTPRequestRedirectFilter
URLRewrite	HTTPURLRewriteFilter
CORS	HTTPCORSFilter
RequestMirror	HTTPRequestMirrorFilter
HTTPExternalAuthFilter	HTTPExternalAuthFilter

Options

Options 部分为 HTTPRoute 提供高级流量管理能力，包括超时、重试和会话保持设置。

Timeouts

字段	描述	YAML 路径
Request Timeout	gateway 在从客户端接收完整 request 后，完成 HTTP response 的最长持续时间。选项：Default（使用默认超时，通常为 15 秒）、Unlimited（设置为 "0s" 以移除超时）、Custom。	`.spec.rules[].timeouts.request`
Backend Request Timeout	单次 gateway 到 backend 调用的最长持续时间，即从 gateway 开始发送 request 到收到完整 backend response 为止。选项：Default（使用实现特定的默认值）、Unlimited（设置为 "0s"）、Custom。	`.spec.rules[].timeouts.backendRequest`

NOTE

Request Timeout 在收到完整 client request 后开始计时，并覆盖完整事务；如果发生重试，可能包含多次 backend 调用。
在指定时，Backend Request Timeout 必须小于或等于 Request Timeout。
选择 “Default” 时，该字段会被设置为 nil（使用实现默认值）。
选择 “Unlimited” 时，该字段会被设置为 "0s"（可达到的最大值）。

字段	规范
`.spec.rules[].timeouts`	HTTPRouteTimeouts

Retry

字段	描述	YAML 路径
Status Codes	触发重试的 HTTP 状态码（例如 503、502）。取值范围：400-599。	`.spec.rules[].retry.codes`
Attempts	重试次数。	`.spec.rules[].retry.attempts`
Backoff	重试前的等待时间（例如 "100ms"、"1s"）。	`.spec.rules[].retry.backoff`

NOTE

默认情况下，重试是禁用的。如果未配置 retry 字段或其为空，gateway 将不会重试任何失败的请求。
必须显式配置重试次数和重试条件，才能启用重试功能。
在 Web Console 中配置重试时，如果你移除了所有重试配置项，该字段会被设置为 nil。

字段	规范
`.spec.rules[].retry`	HTTPRouteRetry

Session Persistence

配置会话亲和性设置，以确保来自同一客户端的请求路由到同一个后端。

字段	描述	YAML 路径
Type	会话保持类型。选项：Cookie、Header。	`.spec.rules[].sessionPersistence.type`
Session Name	用于会话跟踪的 cookie 或 header 名称。	`.spec.rules[].sessionPersistence.sessionName`

字段	规范
`.spec.rules[].sessionPersistence`	SessionPersistence

GRPCRoute Match 和 Filter 参考

以下 match 条件和 filter 类型用于 GRPCRoute。

GRPCRoute Matches

GRPCRoute 支持以下 match 类型：

对象	方法	值类型	描述
Method	-	type (service/method) + value	匹配 gRPC method。Type 可以是 `service`（匹配 service 名称）或 `method`（匹配 method 名称）。
Headers	`Exact`	name (header key) + value	精确匹配 header 值。
	`RegularExpression`	name (header key) + value	正则引擎：RE2。

GRPCRoute Filters

GRPCRoute 仅支持 RequestHeaderModifier filter：

类型	方法	值类型	描述	值要求
RequestHeaderModifier	`Set`	name (string) + value (string)	使用给定的名称和值覆盖 request header	最多 16 项，值：1-4096 个字符
	`Add`	name (string) + value (string)	向 request 添加 header，并追加到现有值	最多 16 项，值：1-4096 个字符
	`Remove`	[]string	从 request 中移除指定的 headers（不区分大小写）	最多 16 项

NOTE

GRPCRoute 不支持超时、重试或会话保持等 Options。

TLSRoute 参考

以下行为是 TLSRoute 特有的。

NOTE

TLSRoute 的 hostnames 是可选的。如果监听器有 hostname，但 TLSRoute 没有，则 TLSRoute 会自动继承监听器的 hostname。
TLSRoute 只能附加到处于 Passthrough 模式的 TLS 协议监听器。

视图

Topology

以下功能是 ACP Web Console 提供的额外查看能力。

Topology 选项卡以可视化方式展示 route 及其关联资源。它会显示附加到该 route 的所有 policy，以及它们的依赖资源，例如被 SecurityPolicy 引用的 secrets。

此功能当前仅适用于 HTTPRoute。

下一步

在 route 已附加到监听器后，如果你需要高级流量或安全策略，请继续阅读 Configure GatewayAPI Policy。更多操作示例请参阅 Tasks for Envoy Gateway。

配置 GatewayAPI Route

目录

概述

前提条件

配置

通过 Web Console 配置

创建 HTTPRoute

Options 配置

创建 TCP/UDP Route

创建 GRPCRoute

创建 TLSRoute

通过 YAML 配置

Route 字段参考

发布到监听器

在 Web Console 中

在 YAML 中

Backend

Hostnames

Rules

Matches

Filters

HTTPRoute 参考

Match Condition Types

Match Condition References

Filter Types

Filter References

Options

Timeouts

Retry

Session Persistence

GRPCRoute Match 和 Filter 参考

GRPCRoute Matches

GRPCRoute Filters

TLSRoute 参考

视图

Topology

下一步

相关任务

#配置 GatewayAPI Route

#目录

#概述

#前提条件

#配置

#通过 Web Console 配置

#创建 HTTPRoute

#Options 配置

#创建 TCP/UDP Route

#创建 GRPCRoute

#创建 TLSRoute

#通过 YAML 配置

#Route 字段参考

#发布到监听器

#在 Web Console 中

#在 YAML 中

#Backend

#Hostnames

#Rules

#Matches

#Filters

#HTTPRoute 参考

#Match Condition Types

#Match Condition References

#Filter Types

#Filter References

#Options

#Timeouts

#Retry

#Session Persistence

#GRPCRoute Match 和 Filter 参考

#GRPCRoute Matches

#GRPCRoute Filters

#TLSRoute 参考

#视图

#Topology

#下一步

#相关任务

配置 GatewayAPI Route

目录

概述

前提条件

配置

通过 Web Console 配置

创建 HTTPRoute

Options 配置

创建 TCP/UDP Route

创建 GRPCRoute

创建 TLSRoute

通过 YAML 配置

Route 字段参考

发布到监听器

在 Web Console 中

在 YAML 中

Backend

Hostnames

Rules

Matches

Filters

HTTPRoute 参考

Match Condition Types

Match Condition References

Filter Types

Filter References

Options

Timeouts

Retry

Session Persistence

GRPCRoute Match 和 Filter 参考

GRPCRoute Matches

GRPCRoute Filters

TLSRoute 参考

视图

Topology

下一步

相关任务