📚 课程目录第2章 Cilium Agent证书体系

2. Cilium Agent 证书体系：TLS/mTLS 原理、CA、身份证书与生命周期

Cilium Agent 之间的通信依赖 mTLS（双向 TLS） 来保证节点身份的真实性与数据机密性。理解证书体系是诊断轮换失败与连通性故障的基础。本章从 TLS/mTLS 原理出发，逐步拆解 CA 架构、Agent 身份证书结构以及证书生命周期管理。

2.1 TLS 与 mTLS 原理对比

特性	TLS（单向）	mTLS（双向）
客户端验证服务端	是（验证服务端证书）	是（验证服务端证书）
服务端验证客户端	否（不要求客户端证书）	是（要求客户端证书）
身份双向绑定	仅服务端身份可验证	双方身份均可验证
Cilium 场景	Hubble UI / API 对外暴露	Agent ↔ Agent 控制面通信

关键点：Cilium Agent 之间的所有控制面通信（如 KVStore 同步、Node 更新、Policy 分发）均使用 mTLS。如果证书轮换失败，Agent 将无法完成握手，导致节点间连通性中断。

2.2 证书颁发机构（CA）架构

Cilium 支持两种 CA 模式：自管理 CA（Self-Managed CA） 和 Kubernetes CSR API 集成 CA。生产环境推荐使用后者，以便与集群 PKI 体系统一。

CA 模式	证书签发方式	轮换策略	适用场景
自管理 CA	Operator 内置 CA 签发	手动或定时轮换	测试、离线环境
Kubernetes CSR CA	通过 k8s CSR API 向集群 CA 申请	自动轮换（依赖 cert-manager 或 kubelet）	生产、多集群

  CA 证书存储位置：CA 根证书通常以 Secret 形式保存在 kube-system 命名空间下，名称为 cilium-ca。Agent 启动时会挂载该 Secret 并验证对端证书链。

2.3 Agent 身份证书结构

每个 Cilium Agent 拥有一个 X.509 v3 身份证书，其中包含以下关键字段：

Subject CN（Common Name）：格式为 cilium-agent-{node-name}，用于标识节点身份。
Subject Alternative Names（SANs）：包含节点 IP、Pod CIDR、节点主机名，用于多网络接口场景。
Key Usage：Digital Signature、Key Encipherment。
Extended Key Usage：Client Authentication、Server Authentication（mTLS 必需）。
Issuer：指向集群 CA 或自管理 CA 的 Subject。

# 查看 Agent 身份证书（示例）
openssl x509 -in /var/run/cilium/certs/agent.crt -text -noout | grep -E "Subject:|Issuer:|X509v3 Subject Alternative Name"
Subject: CN = cilium-agent-k8s-node-01
Issuer: CN = cilium-ca
X509v3 Subject Alternative Name:
    IP Address:10.0.1.5, IP Address:10.0.2.0/24, DNS:node-01.internal

2.4 证书生命周期管理

证书生命周期包含四个阶段：签发 → 分发 → 使用 → 轮换。轮换失败通常发生在“使用”与“轮换”的交接点。

常见轮换失败原因：

CA 根证书过期，导致新签发的 Agent 证书无法被对端信任。
Agent 未及时加载新证书（文件监听失效或重启延迟）。
证书 SAN 与节点实际 IP 不匹配（节点 IP 变更后未重新签发）。
mTLS 握手超时（证书链过长或 CRL 检查阻塞）。

2.5 证书生命周期状态图

下图展示了 Agent 证书从签发到轮换的完整流程，以及各阶段可能出现的故障点。

2.6 证书轮换触发条件

Cilium Agent 证书轮换由以下条件触发：

证书有效期剩余 < 30%（默认策略，可通过 cert-renewal-threshold 调整）。
CA 根证书变更（CA Secret 更新后，所有 Agent 证书需重新签发）。
节点 IP 或主机名变更（触发 SAN 更新）。
手动触发（删除 Agent 证书 Secret 或重启 Operator）。

运维建议：在证书有效期剩余 50% 时提前轮换，避免因网络抖动导致轮换失败。同时开启 --enable-cert-renewal=true 和 --cert-renewal-grace-period=72h 参数。

2.7 证书验证链与信任锚点

Agent 在 mTLS 握手时执行以下验证链：

步骤 1：验证对端证书的 Issuer 是否匹配本地信任的 CA 列表。
步骤 2：验证证书签名是否有效（使用 CA 公钥解密签名）。
步骤 3：验证证书有效期（notBefore 和 notAfter）。
步骤 4：验证 SAN 是否包含对端节点 IP 或主机名。
步骤 5：验证证书是否被吊销（CRL 或 OCSP，可选）。

如果任意一步失败，Agent 将拒绝连接并记录错误日志：

# 典型 mTLS 握手失败日志
level=error msg="mTLS handshake failed" 
  remoteAddr=10.0.1.6:4240 
  error="tls: failed to verify certificate: x509: certificate has expired or is not yet valid"

2.8 证书体系关键参数速查表

参数名	默认值	说明
`cert-renewal-threshold`	0.3（30%）	证书剩余有效期比例低于此值时触发轮换
`cert-renewal-grace-period`	72h	证书过期前宽限期，用于完成轮换
`ca-duration`	365d	CA 根证书有效期
`cert-duration`	90d	Agent 身份证书有效期
`enable-cert-renewal`	true	是否启用自动证书轮换

注意：如果 ca-duration 小于 cert-duration，Agent 证书将在 CA 证书过期后立即失效。生产环境应确保 ca-duration ≥ 2 × cert-duration。

2.9 证书体系故障排查路径

当怀疑证书轮换导致连通性故障时，按以下路径排查：

检查 CA 证书是否过期：openssl x509 -in /var/run/cilium/certs/ca.crt -text -noout | grep -E "notBefore|notAfter"
检查 Agent 证书是否过期：openssl x509 -in /var/run/cilium/certs/agent.crt -text -noout | grep -E "notBefore|notAfter"
检查证书 SAN 是否匹配节点 IP：openssl x509 -in /var/run/cilium/certs/agent.crt -text -noout | grep -A1 "Subject Alternative Name"
检查 mTLS 握手日志：cilium-agent logs --since=10m | grep -i "mTLS\|handshake\|certificate"
手动触发证书轮换：kubectl delete secret -n kube-system cilium-agent-tls-{node-name}（等待 Operator 重新签发）