#配置 GatewayAPI 策略

#概述

本文档介绍如何在 Gateway 和 Route 资源准备就绪后配置策略资源。策略通过 .spec.targetRefs 使用策略附加模式，将额外的流量、安全和后端行为附加到受支持的资源上。

在推荐的工作流中，本文档位于配置 GatewayAPI 路由之后。

Envoy Gateway 目前提供四种策略类型：SecurityPolicy、BackendTLSPolicy、ClientTrafficPolicy 和 BackendTrafficPolicy。

#前提条件

继续操作前，请确保已完成以下操作：

1. 阅读配置 GatewayAPI 网关和配置 GatewayAPI 路由
2. 创建策略将附加到的目标资源，例如 Gateway、Route 或 Service

#策略附加基础

策略通过 .spec.targetRefs 附加到其他资源。

默认情况下，策略只能附加到同一命名空间中的资源。

对于 Gateway 目标，当策略类型支持时，可以使用 sectionName 指定目标监听器。对于 Service 目标，sectionName 指 Service 端口名称。

#策略附加摘要

sectionName 用于指定 Gateway 上的特定监听器，或 Service 上的特定端口。如果省略或 设置为 ALL，策略将应用于所有监听器或端口。

有关 ListenerSet 策略行为和版本限制，请参阅配置 Gateway API ListenerSet。

#在 Web Console 中创建 Policy

所有 Policy 类型都从同一入口创建：

1. 导航至 Alauda Container Platform -> Networking -> Gateway -> Policies
2. 在 Policy Type 下拉菜单中选择所需值
3. 点击 Create Policy 按钮

以下部分仅介绍各 Policy 类型特有的字段。

#SecurityPolicy

#通过 Web Console 配置

通用字段（所有 Policy 共享）：

SecurityPolicy 特有字段：

#API Key Authentication

#CORS Configuration

#通过 YAML 配置

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: demo-security-policy
  namespace: demo
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: demo
  apiKeyAuth:
    credentialRefs:
      - group: ""
        kind: Secret
        name: demo
        namespace: demo
    extractFrom:
      - headers:
          - authorization
  cors:
    allowOrigins:
      - "https://example.com"
    allowMethods:
      - GET
      - POST
    allowHeaders:
      - "Content-Type"
    exposeHeaders:
      - "X-Custom-Header"
    maxAge: "1h"
    allowCredentials: true

#参考

SecurityPolicy 用于为 Gateway 和 Route 配置身份验证、授权及其他安全相关功能。它提供了一种声明式方式，通过在请求到达后端应用程序之前验证传入请求来保护服务。

            Gateway            Route
               |                 |
               +-- SecurityPolicy-+
Client ---> Envoy Listener --------------------> Backend Service

#功能

• 身份验证：使用各种方法（API Key、JWT、OIDC、Basic Auth）验证客户端身份
• 授权：根据已验证的凭据控制对资源的访问
• CORS 配置：管理跨域资源共享策略

#工作原理

1. 创建包含所需身份验证/授权规则的 SecurityPolicy
2. 将其附加到特定的 Gateway、HTTPRoute 或 GRPCRoute
3. Envoy Gateway 根据 Policy 验证传入请求
4. 有效请求将转发到后端服务；无效请求将被拒绝，并返回相应的 HTTP 状态码

#注意事项

1. Web Console 当前支持配置 API Key Authentication 和 CORS。对于其他身份验证方法和高级安全功能，需要使用 YAML 配置。
2. 每个 Route 只能关联一个 SecurityPolicy。
3. 如果 SecurityPolicy 引用了不包含任何值的 Secret，则对附加到该 Route 的所有请求都将返回 401 Unauthorized 并被拒绝。
4. 在 Web Console 中，Extract From 字段默认设置为 header，Header Name 字段默认设置为 authorization。
5. 在 Web Console 中，导航至 Route 的拓扑选项卡，即可查看附加到 Route 的 Policy。

#官方文档

• SecurityPolicy 规范
• API Key Authentication

#BackendTLSPolicy

#通过 Web Console 配置

通用字段：

BackendTLSPolicy 特定字段：

CACertificateRefs 配置：

#通过 YAML 配置

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendTLSPolicy
metadata:
  name: demo-backend-tls-policy
  namespace: demo
spec:
  targetRefs:
    - group: ""
      kind: Service
      name: demo-backend
      namespace: demo
      sectionName: https-port
  validation:
    hostname: backend.example.com
    subjectAltNames:
      - backend.example.com
    cACertificateRefs:
      - group: ""
        kind: Secret
        name: backend-ca
        namespace: demo

#参考

BackendTLSPolicy 控制 Envoy Gateway 与后端服务之间的 TLS 配置。它允许你配置：

                                Service
                                  |
                                  +-- BackendTLSPolicy
Client ---> Envoy Listener --------------------> Backend Service Port
                                  applies here ^

• SNI（Server Name Indication）：与后端建立 TLS 连接时使用的主机名
• 证书验证：验证后端服务器证书的方式
• CA 证书：用于验证后端证书的自定义 CA 证书

#功能

• 配置连接到后端服务时的 TLS 设置
• 支持自定义 CA 证书或系统已知 CA 证书
• 配置 SNI 以完成正确的 TLS 握手

#注意事项

1. targetRefs 中的 sectionName 对应 Service 的端口名称。
2. 使用 WellKnownCACertificates 时，将使用系统的默认 CA 证书进行验证。
3. 主机名为必填项，Envoy 连接后端时将其用作 SNI 值。

#官方文档

• BackendTLSPolicy 规范

#ClientTrafficPolicy

#通过 Web 控制台配置

通用字段：

超时配置（可选）：

#通过 YAML 配置

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: demo-client-traffic-policy
  namespace: demo
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: https
  settings:
    timeout:
      tcp:
        idleTimeout: "30m"
      http:
        requestReceivedTimeout: "60s"
        idleTimeout: "5m"
        streamIdleTimeout: "30s"

#参考

ClientTrafficPolicy 控制客户端到 Envoy Gateway 的连接行为。它可以对以下内容进行细粒度控制：

            Gateway
               |
               +-- ClientTrafficPolicy
Client ---> Envoy Listener --------------------> Backend Service
          applies on the client-facing side ^

• TCP 设置：连接级别的超时和 keepalive 设置
• HTTP 设置：请求/响应超时和 HTTP 协议行为

#功能

• 配置 TCP 连接空闲超时
• 控制 HTTP 请求接收超时
• 设置 HTTP 连接空闲超时
• 配置 HTTP 流空闲超时

#注意事项

1. 超时值以时长字符串表示（例如 "30s"、"5m"、"1h"）。

#官方文档

• ClientTrafficPolicy 规范

#BackendTrafficPolicy

#通过 Web Console 配置

常用字段：

超时配置（选项）：

#通过 YAML 配置

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: demo-backend-traffic-policy
  namespace: demo
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: demo
  settings:
    timeout:
      tcp:
        connectionTimeout: "5s"
      http:
        connectionIdleTimeout: "30m"
        maxConnectionDuration: "1h"
        requestTimeout: "30s"

#参考

BackendTrafficPolicy 控制从 Envoy Gateway 到后端服务的连接行为。它提供以下方面的细粒度控制：

            Gateway / Route
                  |
                  +-- BackendTrafficPolicy
Client ---> Envoy Listener --------------------> Backend Service
                                  applies here ^

• TCP 设置：连接建立超时
• HTTP 设置：连接持续时间、空闲超时和请求超时

#功能

• 配置 TCP 连接建立超时
• 控制 HTTP 连接空闲超时
• 设置 HTTP 连接最长持续时间
• 配置 HTTP 请求超时

#注意事项

1. 超时值以时长字符串表示（例如 "30s"、"5m"、"1h"）。
2. requestTimeout 字段支持设置为 "unlimited" 以禁用超时。

#官方文档

• BackendTrafficPolicy 规范

#相关任务

策略附加后，请继续阅读 Envoy Gateway 任务，了解更多操作示例和高级配置任务。

#商标声明

Envoy® 是 The Linux Foundation 的注册商标。

Alauda 是独立供应商。本产品与 The Linux Foundation 无关联，也未获得其认可或赞助。所有商标均为其各自所有者的财产，在此仅用于标识目的。