K3s 如何用 certificate check 与 certificate rotate 命令检查并轮换组件证书

K3s 如何用 certificate check 与 certificate rotate 命令检查并轮换组件证书

【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s

K3s 的组件证书在磁盘上有明确的有效期，但集群运行期间证书不会自己更新——只有当证书临近过期且 K3s 重启时才会触发自动续期。管理员需要一个主动的检查与轮换手段：先用k3s certificate check查看磁盘上各组件证书的状态与到期时间，再在需要时用k3s certificate rotate轮换证书文件。完成本流程后，你能确认每个组件证书处于OK状态，或按计划完成叶子证书的轮换并验证生效。

前提条件：已有一个运行中的 K3s 集群，你在目标节点（server 或 agent）上可以执行k3s命令，且该节点数据目录中存在对应角色的证书文件。如果你使用了非默认数据目录，命令需通过-d显式指定。

证书生命周期：先弄清哪些证书会被轮换

在动手之前需要区分两类证书，因为certificate rotate只针对第一类：

• 叶子证书（client 和 server 证书，即各组件证书）：自签发起约 365 天有效；
• CA 证书：自签发起约 3650 天（约 10 年）有效，不会自动续期，需要人工介入处理。

依据来自 证书过期检查 ADR。另外注意一处文档间差异：该 ADR 的背景章节提到叶子证书在 K3s 启动时若临近过期（90 天窗口内）会被自动续期，而当前代码中的警告窗口常量 CertificateRenewDays 为 120 天，即check输出中 "will expire within 120 days" 的判定阈值。

第一步：用 certificate check 检查证书状态

check子命令直接读取磁盘上的组件证书并输出状态，不需要连接 API server：

# 默认 text 格式 k3s certificate check # 指定数据目录（非默认数据目录时必须提供） k3s certificate check -d /path/to/k3s-data # 表格 / JSON / YAML 输出，便于人工或脚本处理 k3s certificate check -o table k3s certificate check -o json k3s certificate check -o yaml # 只检查指定服务（可重复指定多个） k3s certificate check --service etcd --service kubelet

行为要点（实现见 pkg/cli/cert/cert.go）：

• 不指定--service（别名-s）时，命令根据数据目录中是否存在 server 数据目录自动判断角色：server 上检查 agent 和 server 全部证书，agent 上只检查 agent 证书；
• --service可选值包括：admin, api-server, controller-manager, scheduler, supervisor, k3s-controller, k3s-server, cloud-controller, etcd, auth-proxy, kubelet, kube-proxy，传了不在列表中的值会直接报错service xxx is not recognized；
• 每张证书的状态为OK、WARNING（距过期不足 120 天）、EXPIRED或NOT YET VALID。

默认 text 输出每一行对应一张证书，格式为（下值为示意，实际内容取决于你的环境）：

serving-kube-apiserver.crt: certificate k3s-server-xxx.k3s.internal (server auth) is ok, expires at 2027-05-01T08:00:00Z etcd.crt: certificate etcd (signing key,server auth,client auth) will expire within 120 days at 2026-11-20T08:00:00Z kubelet.crt: certificate kubelet (client auth) expired at 2026-07-01T08:00:00Z

判断下一步的方式：全部为OK则无需操作；出现WARNING说明该证书将在 120 天窗口内到期，可安排轮换；出现EXPIRED或NOT YET VALID则需要尽快轮换。-o table输出则是带FILENAME / SUBJECT / USAGES / EXPIRES / RESIDUAL TIME / STATUS列的表格形式。

第二步：用 certificate rotate 轮换组件证书

rotate命令把选中的证书文件备份后删除，使 K3s 在下次启动时重新生成新证书。执行前必须清楚它的副作用（见 pkg/cli/cert/cert.go 的rotate实现）：

• 会先把server/tls目录整体复制、并把 agent 侧证书文件复制到备份目录<data-dir>/server/tls-<时间戳>（agent 节点则备份到 agent 数据目录下的同名目录）；
• 然后删除磁盘上对应服务的证书文件——此操作不可通过参数取消，只能靠事先自动生成的备份；
• 在服务列表包含k3s-server时，还会写入触发文件tls/dynamic-cert-regenerate，让 dynamic listener 证书在启动时重新生成；
• 命令结束时会打印Successfully backed up certificates to <备份目录>, please restart k3s server or agent to rotate certificates——也就是说，必须重启 k3s 服务，新证书才会真正生效。

项目自带的集成测试（tests/integration/certrotation/certrotation_int_test.go）给出的完整操作顺序是：停止 k3s → 执行 rotate → 重启 → 验证。按该流程执行：

# 1. 停止 k3s 服务（以 systemd 为例，请替换为实际的停止方式） systemctl stop k3s # 2. 执行轮换（数据目录按实际替换；测试中使用的是 /tmp/certrotationtest） k3s certificate rotate -d /path/to/k3s-data # 3. 重启服务 systemctl start k3s # 4. 只轮换部分服务时使用 --service k3s certificate rotate --service etcd

如果只想轮换某几个组件的证书，用--service筛选；不指定时 server 节点轮换全部证书、agent 节点只轮换 agent 证书，与check的自动检测逻辑一致。

验证轮换结果

服务重启完成后，用check确认所有证书回到OK：

k3s certificate check -d /path/to/k3s-data

集成测试对输出的判定方式是：除第一行 server 信息外，每一行都匹配certificate.*is ok（测试中另允许出现Checking certificates提示行）。

该测试还额外核对了两点，可以作为验证参考：

1. 轮换前后分别对server/tls/serving-kube-apiserver.crt和server/tls/client-ca.crt计算 md5，叶子证书的哈希应当改变（md5sum <data-dir>/server/tls/serving-kube-apiserver.crt | cut -f 1 -d' '）；
2. CA 证书哈希保持不变（client-ca.crt的 md5 前后一致）——这印证了certificate rotate不触碰 CA；
3. 集群默认组件（CheckDefaultDeployments）在重启后恢复就绪，说明轮换没有破坏集群可用性。

常驻监控：cert monitor 控制器

除了手动执行check，K3s 内置了证书过期监控（pkg/certmonitor/certmonitor.go）：

• 每 30 分钟检查一次磁盘证书，注册 Prometheus 指标k3s_certificate_expiration_seconds（按证书 subject 与 usages 打标签的剩余有效期秒数）；
• 节点证书在 120 天窗口内异常时，在 Node 对象上创建CertificateExpirationWarning事件（Warning 类型），提示重启该节点的 K3s 以触发自动轮换；CA 证书在 365 天窗口内异常时创建CACertificateExpirationWarning事件；
• 启动后首次检查无异常时，会创建一条CertificateExpirationOK的 Normal 事件。

这意味着即使不手动跑check，也可以通过 Node 上的事件和指标持续掌握证书状态。

边界与下一步

• certificate rotate只管理叶子证书。CA 证书到期是另一套流程：需要先准备新的 CA 证书，再通过k3s certificate rotate-ca（要求--path指向新 CA 证书目录，可选--force跳过一致性检查）写入 datastore，相关设计与工具见 CA 轮换 ADR 及 contrib/util/rotate-default-ca-certs.sh、contrib/util/generate-custom-ca-certs.sh；
• check与rotate还共享--debug、--config、--log、--also-log-to-stderr等通用标志（定义见 pkg/cli/cmds/certs.go），排查命令本身行为时可用；
• 若check显示某 CA 证书WARNING或EXPIRED，说明 CA 轮换窗口已经打开，应按上述 rotate-ca 流程规划处理，而不是依赖certificate rotate。

【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s