容器与云原生 / 系统课时
治理 TLS 终止与证书引用
治理 TLS 终止与证书引用
入口层 TLS 治理的关键不是“把证书挂上去”,而是明确 TLS 在哪里终止、域名如何与证书匹配,以及 Secret 由谁维护。本课使用 Gateway API 配置 HTTPS Listener,并建立适合多域名入口的证书引用规则。
学习目标
- 配置 Gateway 在入口层终止 HTTPS,并从 Secret 读取 TLS 证书
- 根据域名边界选择 SAN、通配符或独立证书 Secret
- 验证 Listener 是否成功解析证书并进入可用状态
明确 TLS 终止边界
使用 tls.mode: Terminate 时,客户端与 Gateway 之间建立 TLS 连接,Gateway 完成证书选择、握手和解密,再按路由规则把请求转发给后端。后端是否继续使用 TLS 是另一层策略,不能把“入口 HTTPS”直接等同于“端到端加密”。
Gateway 的 HTTPS Listener 通过 certificateRefs 引用 Kubernetes Secret。对标准 Secret 引用而言,证书 Secret 与 Gateway 放在同一 Namespace,可以避免入口组件任意读取其他 Namespace 的私钥,也便于用 Namespace 作为证书管理边界。

创建证书 Secret
下面假设 Gateway 位于 edge Namespace,并已经准备好包含完整证书链的 PEM 文件和对应私钥。实际证书通常由 cert-manager、企业 PKI 或外部证书系统签发;这里仅演示如何把已有证书保存为标准 TLS Secret。
kubectl create namespace edge
kubectl create secret tls api-tls --cert=<PATH>/api.crt --key=<PATH>/api.key -n edge
kubectl create secret tls admin-tls --cert=<PATH>/admin.crt --key=<PATH>/admin.key -n edge预期输出
namespace/edge created
secret/api-tls created
secret/admin-tls created如果 Namespace 已存在,第一条命令会返回 AlreadyExists,不影响后续证书管理。<PATH> 需要替换为实际证书文件路径。
可以确认 Secret 类型和名称,而不打印私钥内容:
kubectl get secret api-tls admin-tls -n edge -o custom-columns=NAME:.metadata.name,TYPE:.type预期输出
NAME TYPE
api-tls kubernetes.io/tls
admin-tls kubernetes.io/tls为不同域名引用证书
下面的 Gateway 使用两个 HTTPS Listener。gatewayClassName 由实际安装的 Gateway Controller 决定,因此应用前需要把 <GATEWAY_CLASS> 替换为集群中真实的 GatewayClass 名称。
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: public-gateway
namespace: edge
spec:
gatewayClassName: <GATEWAY_CLASS>
listeners:
- name: api-https
protocol: HTTPS
port: 443
hostname: api.example.com
tls:
mode: Terminate
certificateRefs:
- group: ""
kind: Secret
name: api-tls
- name: admin-https
protocol: HTTPS
port: 443
hostname: admin.example.com
tls:
mode: Terminate
certificateRefs:
- group: ""
kind: Secret
name: admin-tls这是配置文件示例,生效行为是:客户端携带不同 SNI hostname 建立 HTTPS 连接时,对应 Listener 使用自己的 Secret 完成 TLS 终止。证书的 SAN 必须覆盖 Listener 的 hostname,否则即使 Gateway 接受了配置,客户端仍会报告证书名称不匹配。
将内容保存为 gateway-tls.yaml 后应用:
kubectl apply -f gateway-tls.yaml预期输出
gateway.gateway.networking.k8s.io/public-gateway created验证 Listener 状态
Gateway Controller 会把配置解析结果写入 Gateway 状态。相比只确认资源“创建成功”,更重要的是查看 Listener 是否被接受以及引用是否解析成功。
kubectl get gateway public-gateway -n edge -o jsonpath='{range .status.listeners[*]}{.name}{"\t"}{range .conditions[*]}{.type}{"="}{.status}{" "}{end}{"\n"}{end}'预期结果通常包含类似状态:
api-https Accepted=True ResolvedRefs=True Programmed=True
admin-https Accepted=True ResolvedRefs=True Programmed=True 不同 Gateway Controller 可能增加其他 Condition,Condition 顺序也可能不同,因此应重点确认 Accepted=True 与 ResolvedRefs=True。如果 ResolvedRefs=False,优先检查 Secret 名称、Namespace、Secret 类型以及 Controller 对当前 Gateway API 版本的支持情况。
选择多域名证书策略
多个域名并不意味着必须共享一张证书。域名生命周期、权限边界和故障影响范围不同,证书组织方式也应该不同。
同一业务域下大量动态子域名可以考虑通配符证书,例如 *.example.com;一组固定且共同维护的域名可以使用包含多个 SAN 的证书;管理后台、开放 API 等安全边界明显不同的入口,更适合拆成独立 Listener 和独立 Secret。这样证书轮换、吊销或误配置时,不会一次影响所有域名。
入口 TLS 治理最终应形成清晰的一一映射:域名由 Listener 声明,Listener 明确引用受控的 TLS Secret,证书 SAN 与 hostname 匹配,并通过 Gateway 状态确认引用已经被 Controller 正确解析。