Kubernetes Gateway API BackendTLSPolicy 怎样表达后端 TLS

如果 Gateway 已经把请求转发到 Kubernetes Service，但后端本身还要求 HTTPS，BackendTLSPolicy 就是用来描述“网关如何作为 TLS 客户端连接后端”的资源。它不负责替代 Gateway listener 的下游证书配置，而是通过 targetRefs 绑定 Service，再补充后端连接的 SNI、信任根和可选的证书身份校验。

官方地址：https://gateway-api.sigs.k8s.io/reference/api-types/policy/backendtlspolicy/

真正容易写错的地方有三个：把下游 TLS 和上游 TLS 配在一起、把 Hostname 当成普通域名标签、同时填写两种互斥的 CA 来源。下面按对象范围、身份校验、信任材料和状态观察拆开。

先把下游 TLS 与网关到后端的 TLS 分开

一条经过 Gateway 的 HTTPS 请求至少有两个方向。客户端到 Gateway listener 的 TLS 属于下游连接，通常由 Gateway 的 listener、证书和终止模式描述；Gateway 到后端 Pod 的 TLS 属于上游连接，才是 BackendTLSPolicy 的职责。

因此，后端证书不是写进 Gateway.spec.listeners[].tls.certificateRefs，而是由绑定到 Service 的 BackendTLSPolicy 告诉实现：连接这个 Service 时使用什么服务器名称、怎样信任后端证书。HTTPRoute、GRPCRoute，以及 Terminate 模式的 TLSRoute 都可能落到这条上游连接边界。

用 targetRefs 把策略绑定到 Service

BackendTLSPolicy 是直接附着到后端对象的策略，常规用法是让它与目标 Service 位于同一个命名空间。这样，指向该 Service 的路由可以共享同一份后端 TLS 约束，也避免把跨命名空间的信任关系藏在一条路由里。

下面是一个最小结构示例。示例使用当前 API 参考中的资源形态；真正落地前，要以集群已安装的 Gateway API CRD 和具体实现支持的 API 版本为准。

apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: payments-backend-tls
  namespace: payments
spec:
  # targetRefs 指向被策略约束的后端 Service
  targetRefs:
  - group: ""
    kind: Service
    name: payments
  validation:
    # Hostname 同时提供后端连接使用的 SNI
    hostname: payments.internal.example
    # 生产环境通常引用同命名空间内的 PEM CA 对象
    caCertificateRefs:
    - group: ""
      kind: ConfigMap
      name: payments-backend-ca

这里的关键不是资源名字，而是绑定关系：BackendTLSPolicy -> targetRefs -> Service。不要把策略只绑定到某一条 HTTPRoute，然后期待另一条同样指向该 Service 的路由自动获得一套不同的上游 TLS 语义；实现会按照策略对象和目标引用来处理。

Hostname、SNI 和 SubjectAltNames 不要混用

validation.hostname 表示 Gateway 连接后端时发送的服务器名称指示，也就是 SNI。它不是给读者看的路由别名，而是后端 TLS 服务器选择证书和进行主机名校验时使用的连接身份。官方规则要求它是主机名格式，不能直接写 IP 地址，也不能写通配符主机名。

在最常见的配置里，后端证书的身份与这个 Hostname 对齐即可。需要把“连接时发出的 SNI”和“证书必须具备的身份”拆开时，才考虑 subjectAltNames。例如 SPIFFE 场景可能使用 URI SAN；这时 SNI 仍可使用一个适合后端选证书的主机名，而证书身份改由 URI SAN 进行匹配。

validation:
  # SNI 是网关建立后端 TLS 连接时使用的服务器名称
  hostname: payments.internal.example
  # SAN 校验需要实现支持 BackendTLSPolicySANValidation
  subjectAltNames:
  - type: URI
    # URI SAN 用于表达独立于 SNI 的证书身份
    uri: spiffe://example.com/ns/payments/sa/gateway

配置 SAN 后，不要再把它理解成“Hostname 的别名列表”。它是对后端证书身份的额外约束：证书至少要有一个匹配的 SAN。Hostname、SAN 的类型和具体值还必须符合实现支持的扩展等级；当前 API 参考对 SAN 数量、IP 和通配符都有约束。

CA 信任来源只能选一种

BackendTLSPolicy 的验证配置需要有证书信任来源。常见选择是引用包含 PEM 编码 CA 证书的对象，或者在实现允许时使用系统 CA。caCertificateRefs 与 wellKnownCACertificates 是互斥的，不能为了“更保险”同时填写。

validation:
  hostname: payments.internal.example
  # 方案 A：使用明确的 PEM CA 引用，便于控制信任范围
  caCertificateRefs:
  - group: ""
    kind: ConfigMap
    name: payments-backend-ca

---

validation:
  hostname: public-api.example.com
  # 方案 B：只在实现允许且适合当前环境时使用系统 CA
  wellKnownCACertificates: System

生产环境更适合先确认实现如何读取被引用对象、对象中要求什么键、是否允许跨命名空间引用，再决定 CA 的存放方式。官方 API reference 明确禁止跨命名空间证书引用；系统 CA 的具体集合也可能随实现和运行环境变化，不应把 System 当成所有集群都一致的固定证书包。

options 则是另一类字段：它用于实现特定的扩展配置，例如最低 TLS 版本或密码套件限制。由于这些键不是所有 Gateway 实现都统一解释，使用时要保留域名前缀，并把实现文档作为必读条件，不能只凭 YAML 能提交就认为已生效。

用 PolicyStatus 判断实现是否接受配置

BackendTLSPolicy 的 status 是观察结果，不是用户手动填写的配置。它使用策略祖先状态来报告控制器是否找到目标、是否接受引用以及是否存在实现不支持的字段。排查时先看状态，再看后端服务和证书，不要只看资源是否成功写入 API Server。

# 查看策略状态；只读检查，不修改集群对象
kubectl get backendtlspolicy payments-backend-tls \
  -n payments -o yaml

# 只列出状态条件，便于确认 Accepted、ResolvedRefs 等信息
kubectl get backendtlspolicy payments-backend-tls \
  -n payments \
  -o jsonpath='{range .status.ancestors[*].conditions[*]}{.type}{"="}{.status}{" "}{.reason}{"\n"}{end}'

如果状态提示目标引用无法解析，先检查 Service 名称、命名空间和实现对目标类型的支持；如果引用已解析但连接仍失败，再核对 Hostname 是否与后端证书身份一致、CA 是否包含签发链，以及实现是否支持 SAN 校验或自定义 options。这条顺序能把“对象没绑定上”和“TLS 身份不匹配”区分开。

几个容易混淆的问题

BackendTLSPolicy 能配置客户端到 Gateway 的证书吗？

不能把它当成下游 listener TLS 配置。它描述的是 Gateway 作为客户端连接后端时的 TLS。客户端到 Gateway 的证书、终止或透传仍应在 Gateway listener 和对应的路由语义中处理。

Hostname 写成 Service 的 ClusterIP 可以吗？

不建议也不符合当前 API 对 Hostname 的约束。Hostname 是主机名格式并作为 SNI 使用，IP 地址不是可替代写法。应该让后端证书与实际使用的服务身份匹配。

有了 SNI，为什么还需要 SubjectAltNames？

SNI 解决“连接时告诉后端我要访问哪个名称”，SAN 解决“返回的证书是否具备被接受的身份”。两者通常可以相同，但在 SPIFFE URI 或需要独立证书身份的场景中，拆开表达更清楚。

为什么 YAML 能提交，后端却没有走 TLS？

资源能被 API Server 接收只代表字段形状通过了存储层检查，不代表网关实现已经接受策略。查看 status.ancestors[].conditions，再对照实现的 BackendTLSPolicy 支持等级和已安装 CRD 版本。

小结：BackendTLSPolicy 的核心是把后端 TLS 约束绑定到 Service：targetRefs 决定作用对象，Hostname 提供 SNI，SubjectAltNames 可额外约束证书身份，CA 信任来源在 CACertificateRefs 和 WellKnownCACertificates 中二选一，PolicyStatus 负责告诉你实现如何理解这份策略。先分清上下游边界，再检查身份、信任和状态，配置才不会停留在“YAML 能提交”的层面。