HTTPRoute¶

从 v0.5.0 开始的标准频道

HTTPRoute 资源是 GA，并且自 v0.5.0 开始是标准频道的一部分。有关发布频道的更多信息，请参阅我们的版本控制指南。

HTTPRoute 是一个网关 API 类型，用于指定从网关侦听器到 API 对象（即服务）的 HTTP 请求的路由行为。

规范¶

HTTPRoute 的规范包括

ParentRefs- 定义此路由想要附加到的网关。
主机名（可选）- 定义用于匹配 HTTP 请求的 Host 标头的主机名列表。
规则- 定义对匹配的 HTTP 请求执行操作的规则列表。每个规则都包含匹配、过滤器（可选）、backendRefs（可选）和超时（可选）字段。

以下是将所有流量发送到一个服务的 HTTPRoute 的示例：

附加到网关¶

每个路由都包含一种引用它想要附加到的父资源的方法。在大多数情况下，这将是网关，但这里有一些灵活性，允许实现支持其他类型的父资源。

以下示例显示路由将如何附加到 acme-lb 网关

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httproute-example
spec:
  parentRefs:
  - name: acme-lb

请注意，目标网关需要允许来自路由命名空间的 HTTPRoute 附加，才能使附加成功。

您还可以将路由附加到父资源的特定部分。例如，假设 acme-lb 网关包含以下侦听器

  listeners:
  - name: foo
    protocol: HTTP
    port: 8080
    ...
  - name: bar
    protocol: HTTP
    port: 8090
    ...
  - name: baz
    protocol: HTTP
    port: 8090
    ...

您可以使用 parentRefs 中的 sectionName 字段，仅将路由绑定到侦听器 foo

spec:
  parentRefs:
  - name: acme-lb
    sectionName: foo

或者，您也可以使用 parentRefs 中的 port 字段而不是 sectionName 来实现相同的效果

spec:
  parentRefs:
  - name: acme-lb
    port: 8080

绑定到端口还允许您一次附加到多个侦听器。例如，绑定到 acme-lb 网关的端口 8090 比按名称绑定到相应的侦听器更方便

spec:
  parentRefs:
  - name: acme-lb
    sectionName: bar
  - name: acme-lb
    sectionName: baz

但是，当按端口号绑定路由时，网关管理员将不再能够灵活地切换网关上的端口，而无需同时更新路由。此方法仅应在路由应应用于特定端口号（而不是端口可能更改的侦听器）时使用。

主机名¶

主机名定义用于匹配 HTTP 请求的 Host 标头的主机名列表。当发生匹配时，将选择 HTTPRoute 以根据规则和过滤器（可选）执行请求路由。主机名是网络主机的完全限定域名，如 RFC 3986 中所定义。请注意以下与 RFC 中定义的 URI 的“主机”部分的偏差

不允许使用 IP 地址。
不尊重 : 分隔符，因为不允许使用端口。

在评估 HTTPRoute 规则之前，会将传入请求与主机名进行匹配。如果未指定主机名，则将根据 HTTPRoute 规则和过滤器（可选）路由流量。

以下示例定义主机名 "my.example.com"

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httproute-example
spec:
  hostnames:
  - my.example.com

规则¶

规则定义根据条件匹配 HTTP 请求的语义，可选地执行额外的处理步骤，并可选地将请求转发到 API 对象。

匹配¶

匹配定义用于匹配 HTTP 请求的条件。每个匹配都是独立的，即如果满足任何一个匹配，则将匹配此规则。

以下匹配配置为例

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
...
spec:
  rules:
  - matches:
    - path:
        value: "/foo"
      headers:
      - name: "version"
        value: "2"
    - path:
        value: "/v2/foo"

要使请求与该规则匹配，它必须满足以下任一条件

路径以 /foo 为前缀，并且包含标头 "version: 2"
路径前缀为 /v2/foo

如果没有指定匹配项，则默认情况下为路径前缀匹配“/”，其效果是匹配每个 HTTP 请求。

过滤器（可选）¶

过滤器定义请求或响应生命周期中必须完成的处理步骤。过滤器充当扩展点，用于表达可能在网关实现中执行的额外处理。一些示例包括请求或响应修改、实施身份验证策略、速率限制和流量整形。

以下示例将标头 "my-header: foo" 添加到具有 Host 标头 "my.filter.com" 的 HTTP 请求中。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-filter-1
spec:
  hostnames:
    - my.filter.com
  rules:
    - filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: my-header
                value: foo
      backendRefs:
        - name: my-filter-svc1
          weight: 1
          port: 80

API 一致性是根据过滤器类型定义的。多个行为的排序效果目前未指定。这可能会在 alpha 阶段根据反馈而改变。

一致性级别由过滤器类型定义

所有“核心”过滤器必须由实现支持。
鼓励实施者支持“扩展”过滤器。
“特定于实现”的过滤器在不同实现之间没有 API 保证。

多次指定核心过滤器具有未指定或特定于实现的一致性。

所有过滤器都应该彼此兼容，除了 URLRewrite 和 RequestRedirect 过滤器，它们可能不能组合使用。如果实现无法支持过滤器的其他组合，则它们必须清楚地记录该限制。在指定不兼容或不支持的过滤器并导致 Accepted 条件设置为状态 False 的情况下，实现可以使用 IncompatibleFilters 原因来指定此配置错误。

BackendRefs（可选）¶

BackendRefs 定义应该将匹配请求发送到的 API 对象。如果未指定，则规则不会执行转发。如果未指定且未指定会产生响应的过滤器，则返回 404 错误代码。

以下示例将前缀为 /bar 的 HTTP 请求转发到端口为 8080 的服务 "my-service1"，并将具有标头 magic: foo 的前缀为 /some/thing 的 HTTP 请求转发到端口为 8080 的服务 "my-service2"

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example
spec:
  controllerName: acme.io/gateway-controller
  parametersRef:
    name: example
    group: acme.io
    kind: Parameters
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: example
  listeners:  # Use GatewayClass defaults for listener definition.
  - name: http
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-app-1
spec:
  parentRefs:
  - name: my-gateway
  hostnames:
  - "foo.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /bar
    backendRefs:
    - name: my-service1
      port: 8080
  - matches:
    - headers:
      - type: Exact
        name: magic
        value: foo
      queryParams:
      - type: Exact
        name: great
        value: example
      path:
        type: PathPrefix
        value: /some/thing
      method: GET
    backendRefs:
    - name: my-service2
      port: 8080

以下示例使用 weight 字段将 90% 的前缀为 /foo 的 HTTP 请求转发到 "foo-v1" 服务，其余 10% 转发到 "foo-v2" 服务

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: foo-route
  labels:
    gateway: prod-web-gw
spec:
  hostnames:
  - foo.example.com
  rules:
  - backendRefs:
    - name: foo-v1
      port: 8080
      weight: 90
    - name: foo-v2
      port: 8080
      weight: 10

有关 weight 和其他字段的更多详细信息，请参阅 backendRef API 文档。

超时（可选）¶

自 v1.0.0 以来为实验性频道

HTTPRoute 超时自 v1.0.0 以来一直是实验性频道的组成部分。有关发布频道的更多信息，请参阅我们的版本控制指南。

HTTPRoute 规则包含 Timeouts 字段。如果未指定，则超时行为是特定于实现的。

HTTPRoute 规则中可以配置两种类型的超时

request 是 Gateway API 实现向客户端 HTTP 请求发送响应的超时时间。此超时时间旨在涵盖尽可能接近整个请求-响应事务的时间，尽管实现可以 CHOOSE 在接收完整个请求流后才开始超时，而不是在客户端启动事务后立即开始。
backendRequest 是 Gateway 向后端发送单个请求的超时时间。此超时时间涵盖从请求开始从 Gateway 发送到从后端接收完整响应的时间。如果 Gateway 尝试重新连接到后端，这将特别有用。

因为 request 超时包含 backendRequest 超时，所以 backendRequest 的值不能大于 request 超时的时间。

超时是可选的，它们的字段类型为 Duration。零值超时 ("0s") 必须被解释为禁用超时。有效非零值超时必须 >= 1ms。

以下示例使用 request 字段，如果客户端请求完成时间超过 10 秒，则会导致超时。该示例还定义了一个 2 秒的 backendRequest，它指定了从 Gateway 到后端服务 timeout-svc 的单个请求的超时时间

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: timeout-example
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /timeout
    timeouts:
      request: 10s
      backendRequest: 2s
    backendRefs:
    - name: timeout-svc
      port: 8080

有关更多详细信息，请参阅 timeouts API 文档。

后端协议¶

自 v1.0.0 以来为实验性频道

此概念自 v1.0.0 以来一直是实验性频道的组成部分。有关发布频道的更多信息，请参阅我们的版本控制指南。

某些实现可能需要明确标记 backendRef 以便使用特定协议路由流量。对于 Kubernetes 服务后端，可以通过指定 appProtocol 字段来实现这一点。

状态¶

Status 定义了 HTTPRoute 的观察状态。

RouteStatus¶

RouteStatus 定义了所有路由类型都需要观察到的状态。

父级¶

Parent 定义了与 HTTPRoute 关联的网关（或其他父资源）的列表，以及 HTTPRoute 相对于每个网关的状态。当 HTTPRoute 在 parentRefs 中添加对网关的引用时，管理网关的控制器应该在控制器第一次看到路由时在该列表中添加一个条目，并且应该在路由被修改时根据需要更新该条目。

以下示例表明 HTTPRoute "http-example" 已被命名空间 "gw-example-ns" 中的网关 "gw-example" 接受。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-example
...
status:
  parents:
  - parentRefs:
      name: gw-example
      namespace: gw-example-ns
    conditions:
    - type: Accepted
      status: "True"

合并¶

多个 HTTPRoute 可以附加到单个网关资源。重要的是，每个请求只能匹配一条路由规则。有关冲突解决如何应用于合并的更多信息，请参阅 API 规范。