K3s 如何用 certificate check 与 certificate rotate 命令检查并轮换组件证书【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3sK3s 的组件证书在磁盘上有明确的有效期但集群运行期间证书不会自己更新——只有当证书临近过期且 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确认所有证书回到OKk3s certificate check -d /path/to/k3s-data集成测试对输出的判定方式是除第一行 server 信息外每一行都匹配certificate.*is ok测试中另允许出现Checking certificates提示行。该测试还额外核对了两点可以作为验证参考轮换前后分别对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 CA 证书哈希保持不变client-ca.crt的 md5 前后一致——这印证了certificate rotate不触碰 CA集群默认组件CheckDefaultDeployments在重启后恢复就绪说明轮换没有破坏集群可用性。常驻监控cert monitor 控制器除了手动执行checkK3s 内置了证书过期监控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.shcheck与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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 K3s 如何用 certificate check 与 certificate rotate 命令检查并轮换组件证书
K3s 如何用 certificate check 与 certificate rotate 命令检查并轮换组件证书【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3sK3s 的组件证书在磁盘上有明确的有效期但集群运行期间证书不会自己更新——只有当证书临近过期且 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确认所有证书回到OKk3s certificate check -d /path/to/k3s-data集成测试对输出的判定方式是除第一行 server 信息外每一行都匹配certificate.*is ok测试中另允许出现Checking certificates提示行。该测试还额外核对了两点可以作为验证参考轮换前后分别对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 CA 证书哈希保持不变client-ca.crt的 md5 前后一致——这印证了certificate rotate不触碰 CA集群默认组件CheckDefaultDeployments在重启后恢复就绪说明轮换没有破坏集群可用性。常驻监控cert monitor 控制器除了手动执行checkK3s 内置了证书过期监控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.shcheck与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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考