K3s 默认自签 CA 到期前如何用 rotate-default-ca-certs.sh 轮换集群 CA 证书【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3sK3s 在集群首次启动时会自动生成一套自签 CA——Server CA、Client CA、Request Header CA、etcd Peer CA、etcd Client CA外加 ServiceAccount Token 签名密钥。这些 CA 证书有效期为 3650 天约 10 年且不会自动续期一旦任何一张 CA 过期由它签发的证书都会失效导致集群大范围故障。这篇文章给出在默认自签 CA 到期前完成轮换的完整路径用仓库提供的示例脚本 rotate-default-ca-certs.sh 生成新的交叉签名 CA 证书再用k3s certificate rotate-ca写入集群数据。需要说明的前提这是针对首次启动时自动生成自签 CA的集群的轮换流程。按 ca-cert-rotation ADR 的定义它属于“disruptive有中断”的更新——必须在重启服务前修改节点的 CLI flag、配置文件或环境变量主要是 token且配置应用到所有节点的过程中集群节点可能因暂时不共享同一信任根而出现短暂不可用。轮换前确认 CA 证书的到期状态先运行证书检查命令确认当前 CA 还剩多久到期k3s certificate check该命令输出每个证书文件的文件名、Subject、用途、过期时间和状态状态取值为OK、WARNING、EXPIRED或NOT YET VALID也可以用-o table、-o json、-o yaml切换输出格式。对比轮换前后的 CA 到期时间、以及轮换后各证书状态回到OK是本文验证步骤的核心手段。作为对照叶子证书客户端/服务端证书有效期为 365 天会在 K3s 启动时若距过期不足 90 天自动续期不需要手动处理需要人工介入的只有 CA。准备条件在运行 k3s server 的节点上操作。脚本默认数据目录DATA_DIR/var/lib/rancher/k3s如果你的 k3s 使用了-data-dir指定其他目录运行时通过环境变量DATA_DIR覆盖。节点上需要有带椭圆曲线ecparam支持的 openssl。脚本启动时会自检缺失时报错openssl not found or missing Elliptic Curve (ecparam) support.并退出如果系统里有openssl-3命令会优先使用它。脚本会检查数据目录下 5 个 CA 证书文件是否存在client-ca.crt、server-ca.crt、request-header-ca.crt、etcd/peer-ca.crt、etcd/server-ca.crt位于${DATA_DIR}/server/tls/。任何一个缺失都会输出Current type CA cert does not exist; cannot continue并退出。脚本的副作用范围在${DATA_DIR}/server/rotate-ca下创建新的证书和密钥文件以及一个脚本退出时自动清理的临时.ca工作目录。它不会修改数据目录中已有的证书是否生效取决于后续rotate-ca步骤。把脚本从 k3s 源码树中取出放到 server 节点上仓库内路径为 contrib/util/rotate-default-ca-certs.sh例如放到节点上的/tmp与 e2e 测试中的用法一致。步骤一生成新的交叉签名 CA执行脚本使用默认数据目录时直接运行即可数据目录不同则加DATA_DIRbash /tmp/rotate-default-ca-certs.sh# 数据目录不是 /var/lib/rancher/k3s 时 DATA_DIR/你的k3s数据目录 bash /tmp/rotate-default-ca-certs.sh脚本对每种 CA 类型执行三步生成新的自签根 CA有效期 7300 天、用当前旧根 CA 对新根做交叉签名、再由新根签发新的叶子 CA。最终生成的 CA bundle 会依次包含新叶子 CA、新自签根、交叉签名根、旧根。保留旧根意味着已签发的现有证书在原始根 CA 过期之前仍然被信任这是交叉签名流程的核心目的。脚本还会生成新的 ServiceAccount 签名密钥一个新的 RSA 2048 密钥加上旧service.key的内容。服务端写入时会校验新密钥 bundle 中仍包含当前生效的签名密钥旧 token 的验签不受影响。脚本正常结束后会打印类似如下内容文档示例具体哈希值以你的集群为准Cross-signed CA certs and keys now available in /var/lib/rancher/k3s/server/rotate-ca Updated server token: K10新server-ca哈希::原token第二部分 Updated agent token: K10新server-ca哈希::原token第二部分 To update certificates, you may now run: k3s certificate rotate-ca --path/var/lib/rancher/k3s/server/rotate-ca这里的更新 token 必须记下来完整K10格式的 token 中包含 Server CA 文件的 SHA256 哈希CA 更换后哈希随之变化旧 token 将不再通过节点加入时的 CA 哈希校验见 ca-cert-rotation ADR 中 “Server CA Pinning” 一节。步骤二把新 CA 写入集群数据按脚本提示执行k3s certificate rotate-ca --path/var/lib/rancher/k3s/server/rotate-ca参数说明--path为必填项指向步骤一生成的目录。命令使用数据目录下的 server token 向 API server 的/v1-k3s/cert/cacerts端点 PUT 新证书--server默认为https://127.0.0.1:6443。服务端写入前会做一致性校验新的叶子 CA 必须能用旧 CA 链验证即共享同一信任根新的 ServiceAccount 签名密钥 bundle 必须包含当前生效密钥。校验失败时命令报错failed to validate new CA certificates and keys并提示see server log for details。如果确实需要在一致性检查失败时强行写入可加--force用法说明为 “Force certificate replacement, even if consistency checks fail”仅在明确理解后果时使用。成功时命令输出certificates saved to datastore同时 server 日志会记录certificate: Cluster Certificate Authority data has been updated, k3s must be restarted.——即证书已落库但节点必须重启才会加载。步骤三更新 agent token 并重启节点把每个 agent 节点使用的 token通过配置文件、环境变量或 CLI flag 提供的那份更新为脚本输出的 “Updated agent token”。这是 disruptive 更新要求的配置变更必须在重启服务之前完成。重启所有 k3s server 节点再重启 agent 节点。集成测试与 e2e 测试均采用“先停 server、再启动、随后重启其余节点”的顺序见 cacertrotation 集成测试 和 rotateca e2e 测试。重启窗口内集群可能出现短暂不可用属于该流程的预期现象不是故障。验证轮换结果检查 CA 到期时间是否更新。在 server 节点上运行k3s certificate check确认 CA 证书条目显示新的过期时间、状态为OK。确认 CA 文件确实被替换。集成测试的做法是轮换前后各取一次哈希并比较md5sum /var/lib/rancher/k3s/server/tls/client-ca.crt md5sum /var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt测试断言轮换并重启 server 后client-ca.crtCA 被替换和serving-kube-apiserver.crt用新 CA 链重新签发的哈希都与轮换前不同。确认集群功能恢复各节点进入 Ready 状态、kube-system命名空间中的 Pod 全部 running。这是 e2e 测试在重启 server 和 agent 之后的验证方式。限制与注意该流程只适用于默认自签 CA 的集群。如果集群启动时使用了外部 CA 签发的用户自定义证书非中断式更新只需重启服务、无需改节点配置即可仓库另提供了 generate-custom-ca-certs.sh 作为对应工具。步骤一脚本要求 5 张 CA 证书齐全任何一张缺失都会直接终止不会做部分轮换。新 CA bundle 中包含旧根现有证书的可信状态延续到旧根过期为止不要手动编辑server/rotate-ca目录下的文件后再执行rotate-ca否则可能触发一致性校验失败。更多背景hash 钉扎、bootstrap 数据不可重写等问题可参考 docs/adrs/ca-cert-rotation.md证书到期检查机制参考 docs/adrs/cert-expiry-checks.md。【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考