TLS / mTLS

Nantian Gateway 支持三条通信通道的 TLS：Admin HTTP API、控制面与数据面之间的 gRPC xDS 流，以及数据面侧的 xDS 传输。每条通道独立配置。

控制面 TLS

控制面暴露两个支持 TLS 的服务器：Admin HTTP 服务器和 gRPC xDS 服务器。

Admin TLS

为 Admin HTTP API 提供服务器端 TLS 保护：

参数	类型	默认值	说明
adminTLS.enabled	bool	false	启用 Admin HTTP 服务器的 TLS
adminTLS.cert_path	string	""	服务器证书文件路径（PEM 格式）
adminTLS.key_path	string	""	服务器私钥文件路径（PEM 格式）

启用后，Admin 服务器使用 HTTPS 而非 HTTP。证书和私钥必须是控制面进程可读取的有效 PEM 编码文件。在 Kubernetes 中，通过 Secret 卷挂载这些文件。

证书轮换

控制面不会监控证书文件变更。轮换证书需要重启控制面进程。在 Kubernetes 中，滚动更新期间会自动完成此操作。

gRPC TLS

为 gRPC xDS 流提供 TLS 保护，可选双向 TLS：

参数	类型	默认值	说明
grpcTLS.enabled	bool	false	启用 gRPC 服务器的 TLS
grpcTLS.cert_path	string	""	服务器证书文件路径（PEM 格式）
grpcTLS.key_path	string	""	服务器私钥文件路径（PEM 格式）
grpcTLS.clientCAPath	string	""	用于验证客户端证书的 CA 证书路径
grpcTLS.requireClientCert	bool	false	要求并验证客户端证书（mTLS）

将 requireClientCert 设置为 true 启用双向 TLS。每个连接的数据面必须提供由 clientCAPath 指定的 CA 签发的证书。未启用 mTLS 时，任何能够访问 gRPC 端口的客户端都可以接收配置快照。

生产环境 gRPC

gRPC 流传输完整的网关配置，包括路由规则、后端地址和 TLS 密钥。生产环境中务必启用 gRPC TLS 并配置 mTLS。未启用时，拥有 gRPC 端口网络访问权限的任何方均可拦截或注入配置。

数据面 TLS

数据面有两个 TLS 相关配置部分：代理运行时（面向客户端的 TLS）和 xDS 传输（控制面连接）。

代理运行时 TLS

这些设置控制流经数据面的流量的 TLS 行为：

参数	类型	默认值	说明
runtime.tls_min_version	string	"1.2"	接受的最低 TLS 版本（"1.2" 或 "1.3"）
runtime.tls_max_version	string	"1.3"	接受的最高 TLS 版本（"1.2" 或 "1.3"）

xDS 传输 TLS

配置数据面如何连接控制面的 gRPC 服务器：

参数	类型	默认值	说明
xds_tls.enabled	bool	false	启用 xDS 连接的 TLS
xds_tls.domain_name	string	""	用于证书验证的预期服务器名称
xds_tls.ca_path	string	""	用于验证服务器的 CA 证书路径
xds_tls.cert_path	string	""	客户端证书路径（用于 mTLS）
xds_tls.key_path	string	""	客户端私钥路径（用于 mTLS）

当同时设置 cert_path 和 key_path 时，数据面向控制面提供客户端证书，满足 gRPC 服务器上启用 requireClientCert 时的 mTLS 要求。

示例：完整 mTLS 配置

以下配置在 gRPC 流上启用 mTLS，并在 Admin API 上启用 TLS：

# 控制面
grpcTLS:
  enabled: true
  cert_path: /etc/certs/grpc/tls.crt
  key_path: /etc/certs/grpc/tls.key
  clientCAPath: /etc/certs/grpc/ca.crt
  requireClientCert: true

adminTLS:
  enabled: true
  cert_path: /etc/certs/admin/tls.crt
  key_path: /etc/certs/admin/tls.key

# 数据面
xds_tls:
  enabled: true
  domain_name: nantian-gw-controlplane-grpc.nantian-gw.svc
  ca_path: /etc/certs/xds/ca.crt
  cert_path: /etc/certs/xds/tls.crt
  key_path: /etc/certs/xds/tls.key

证书管理

证书可通过以下几种方式配置：

• cert-manager — 使用 Kubernetes cert-manager 操作器自动签发和轮换证书
• 手动配置 — 使用 openssl 或 cfssl 等工具生成证书，并以 Kubernetes Secret 形式挂载
• Vault — 集成 HashiCorp Vault 进行集中式证书管理

生产部署推荐使用 cert-manager。它无需人工干预即可处理证书签发、续期和轮换。

自动回退 TLS 证书

当您在 Gateway 上配置 HTTPS 监听器但未设置 certificateRefs 时，Nantian Gateway 控制平面将自动生成自签 TLS 证书，使监听器能立即提供 HTTPS 服务。

注意

这是开发阶段的便捷功能。回退证书提供加密（TLS），但不提供身份验证——证书是自签的，不经过任何 CA 信任。生产环境请务必通过 certificateRefs 配置正式证书。

工作原理

1. 启动时，控制平面创建持久化 CA 证书，存储在 Kubernetes Secret nantian-gw-fallback-ca 中（命名空间与控制平面相同）
2. 对每个未配置 certificateRefs 的 HTTPS 监听器，使用该 CA 签发叶子证书，监听器的 hostname 作为 SAN 条目
3. 证书和密钥通过 xDS 协议推送到数据平面，与用户配置的证书处理方式一致
4. CA 证书在重启后保持不变——重启前签发的叶子证书继续有效

回退 CA Secret

控制平面创建并管理以下 Secret：

apiVersion: v1
kind: Secret
metadata:
  name: nantian-gw-fallback-ca
  namespace: nantian-gw
  labels:
    app.kubernetes.io/managed-by: nantian-gw
    nantian.dev/component: fallback-ca
type: kubernetes.io/tls
data:
  tls.crt: <CA certificate PEM>
  tls.key: <CA private key PEM>

请勿在有回退证书监听器处于活跃状态时删除该 Secret——删除会导致下一次控制平面重启时生成新的 CA，使之前签发的所有叶子证书失效。

下一步

• 配置概述 — 通用配置结构
• 安全最佳实践 — 运维安全指南
• 生产环境部署 — 生产级安装