#配置 GatewayAPI 策略

#概述

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

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

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

#前提条件

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

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

#策略附加基础

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

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

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

#策略附加汇总

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

#在 Web 控制台创建策略

所有策略类型均从同一入口创建：

1. 进入 Alauda Container Platform -> Networking -> Gateway -> Policies
2. 在 Policy Type 下拉框中选择所需的值
3. 点击 Create Policy 按钮

以下章节仅关注各策略类型特有的字段。

#SecurityPolicy

#通过 Web 控制台配置

通用字段（所有策略共享）：

SecurityPolicy 特有字段：

#API Key Authentication

#CORS 配置

#通过 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 和路由的身份验证、授权及其他安全相关功能。它提供声明式方式，在请求到达后端应用之前验证请求，从而保护服务。

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

#功能

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

#工作原理

1. 创建包含所需身份验证/授权规则的 SecurityPolicy
2. 将其附加到特定的 Gateway、HTTPRoute 或 GRPCRoute
3. Envoy Gateway 根据策略验证传入请求
4. 合法请求转发至后端服务；非法请求返回相应 HTTP 状态码拒绝访问

#注意事项

1. Web 控制台当前支持配置 API Key Authentication 和 CORS。其他身份验证方式及高级安全功能需使用 YAML 配置。
2. 每个路由只能关联一个 SecurityPolicy。
3. 如果 SecurityPolicy 引用的 secret 无值，则所有请求都会被拒绝，返回 401 Unauthorized。
4. Web 控制台中，默认 Extract From 字段为 header，Header Name 字段为 authorization。
5. 可在 Web 控制台的路由拓扑标签页查看附加到路由的策略。

#官方文档

• SecurityPolicy 规范
• API Key Authentication

#BackendTLSPolicy

#通过 Web 控制台配置

通用字段：

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
                                  应用在此 ^

• SNI（服务器名称指示）：建立 TLS 连接时使用的主机名
• 证书验证：如何验证后端服务器证书
• CA 证书：用于验证后端证书的自定义 CA 证书

#功能

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

#注意事项

1. targetRefs 中的 sectionName 对应 Service 的端口名称。
2. 使用 WellKnownCACertificates 时，使用系统默认 CA 证书进行验证。
3. hostname 为必填项，作为 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
          应用在客户端侧 ^

• TCP 设置：连接级别的超时和保持活动设置
• HTTP 设置：请求/响应超时及 HTTP 协议行为

#功能

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

#注意事项

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

#官方文档

• ClientTrafficPolicy 规范

#BackendTrafficPolicy

#通过 Web 控制台配置

通用字段：

超时配置（选项）：

#通过 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
                                  应用在此 ^

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

#功能

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

#注意事项

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

#官方文档

• BackendTrafficPolicy 规范

#相关任务

策略附加完成后，请继续参考Envoy Gateway 任务获取更多操作示例和高级配置任务。