#配置 GatewayAPI Policy

#概述

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

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

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

#前提条件

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

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

#Policy Attachment 基础

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

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

对于 Gateway 目标，当 policy 类型支持时，可以使用 sectionName 指定某个特定的 listener。对于 Service 目标，sectionName 表示 Service 端口名称。

#Policy Attachment 概览

sectionName 用于指定 Gateway 上的特定 listener，或 Service 上的特定端口。若省略，或设置为 ALL，则该 policy 适用于所有 listener 或端口。

#在 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 Configuration：管理跨域资源共享策略

#工作原理

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 的 topology 选项卡 来查看某个 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 连接时使用的 hostname
• Certificate Validation：如何验证后端服务器证书
• CA Certificates：用于验证后端证书的自定义 CA 证书

#功能

• 为连接到后端服务的连接配置 TLS 设置
• 支持自定义 CA 证书或系统已知 CA 证书
• 提供正确 TLS 握手所需的 SNI 配置

#说明

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

#官方文档

• BackendTLSPolicy 规范

#ClientTrafficPolicy

#通过 Web Console 配置

通用字段：

超时配置（选项）：

#通过 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 Settings：连接级超时和 keepalive 设置
• HTTP Settings：请求/响应超时和 HTTP 协议行为

#功能

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

#说明

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 Settings：连接建立超时
• HTTP Settings：连接持续时间、空闲超时和请求超时

#功能

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

#说明

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

#官方文档

• BackendTrafficPolicy 规范

#相关任务

在附加 policy 之后，继续查看 Envoy Gateway 的任务，了解更多 运维示例和高级配置任务。