本文永久链接: https://www.xtplayer.cn/rke2/server-token-rotate/

为什么需要 Server Token 轮换？

RKE2 使用 Token 来保障节点加入集群的安全，并对持久化到数据存储中的机密信息进行加密。Server Token 拥有最高权限，其重要性体现在两个方面：

  • 认证凭证：Server Token 可用于将任何新节点（无论是 Server 还是 Agent）加入集群。这意味着，任何持有此 Token 的人，都等同于拥有集群的完全管理员权限。
  • 加密密钥：Server Token 还充当 PBKDF2 的加密口令，用于加密存储在数据存储（ETCD）中的核心机密数据，即“引导数据”（bootstrap data）。引导数据对于新 Server 节点的加入和从快照恢复集群至关重要。

正因为 Server Token 既是“通行证”又是“保险柜钥匙”，它在日常运维中面临多重泄露风险：

  • 配置管理不当：Token 可能被明文写入自动化脚本、配置文件（如 config.yaml）或代码仓库中，意外泄露。有用户就曾在社区反馈，自己不慎将 Token 提交到了自动化仓库中。
  • 运维操作暴露：在多节点复制 Token 的过程中，可能通过不安全的渠道（如明文消息、剪贴板）传播。
  • 节点文件权限：Token 文件（通常位于 /var/lib/rancher/rke2/server/token 和 /etc/rancher/rke2/config.yaml）如果权限设置不当（如被低权限用户或进程读取），也可能导致泄露。

一旦 Server Token 泄露，攻击者不仅可以向集群中注入恶意节点，还能尝试解密数据存储中的关键信息。因此，定期轮换 Server Token 是缩小攻击面、符合安全合规要求（如定期更换密码/密钥策略）的关键运维动作。

轮换 Server Token 的操作步骤

RKE2 从 v1.28.3+rke2r2、v1.27.7+rke2r2、v1.26.10+rke2r2 及 v1.25.15+rke2r2 版本开始，正式提供了 rke2 token rotate 命令来支持 Server Token 的轮换。操作流程如下：

准备工作

  • 确保集群健康：在执行任何轮换操作前，确认所有节点状态均为 Ready。
  • 记录旧 Token：务必备份当前的旧 Token。如果将来需要从快照恢复集群，必须使用与该快照关联的 Token。
  • 准备新 Token：你可以通过 --new-token 参数指定一个新 Token，如果不指定，系统将自动生成一个 16 字符的随机 Token。

执行轮换

在任意一台 Server 节点上，执行 rke2 token rotate 命令。注意：只需要在一台 Server 节点执行此命令。

# 使用旧 Token 指定并设置新 Token
sudo rke2 token rotate --token <旧Token> --new-token=<新Token>

# 或者，让系统自动生成新 Token
sudo rke2 token rotate --token <旧Token>

执行后，你会看到类似 Token rotated, restart rke2 nodes with new token 的提示。

更新配置并重启所有节点

此步骤是关键且风险较高的环节，需要按顺序操作。

  1. 更新并重启所有 Server 节点

    • 在每个 Server 节点的配置文件中（通常是 /etc/rancher/rke2/config.yaml），将 token 字段的值修改为新 Token。

    • 逐个重启 Server 节点服务：

      sudo systemctl restart rke2-server

    • 务必等待第一个 Server 节点完全启动并恢复集群 Leader 状态后，再操作下一个 Server 节点。

  2. 更新并重启所有 Agent 节点

    • 在每个 Agent 节点的配置文件中，更新 token 字段。

    • 逐个重启 Agent 服务：

      sudo systemctl restart rke2-agent

验证

所有节点重启完成后，执行 kubectl get nodes 验证所有节点状态是否为 Ready，集群功能是否正常。

风险与注意事项

虽然官方提供了工具，但 Server Token 轮换在实践中有诸多风险，必须高度警惕。

风险一：集群重启失败（最常见）

这是最致命的风险。重启 Server 节点时，RKE2 需要将磁盘上的引导数据与数据存储（ETCD）中的信息进行核对。如果 Token 不匹配，将导致服务启动失败，错误信息如下：

level=fatal msg="Failed to reconcile with temporary etcd: bootstrap data already found and encrypted with different token"

根本原因：在轮换操作中，rke2 token rotate 命令更新了数据存储中的 Token 信息，并更新了本地的 /var/lib/rancher/rke2/server/cred/passwd 文件。但如果在更新配置文件前重启了服务，或者有其他 Server 节点的 passwd 文件未同步，就会导致加密口令不匹配，服务无法启动。

应对策略：严格执行“先更新配置，再逐个重启”的顺序。如果遇到此错误，社区建议是删除本地的 passwd 文件，让服务重启时从数据存储中重新拉取正确的凭证。

风险二：历史版本兼容性问题

虽然官方文档和社区验证表明，在较新版本（如 v1.28.2+）中该功能是正常的，但在一些特定版本或发行版中，该命令存在已知问题。

例如，在 Harvester v1.3.0（内嵌 RKE2 v1.27.10+rke2r1）中，执行 rke2 token rotate 后会导致服务无法启动，Harvester 官方明确警告用户 “在 Harvester 宣布正式支持此功能前，不要尝试轮换 RKE2 Token”。这提醒我们，生产环境的操作必须严格参考所使用的具体 RKE2 版本的官方文档。

风险三：快照恢复失败

这是一个容易被忽视的长期风险。官方文档和命令输出中都明确警告：如果将来需要从快照恢复集群，必须使用该快照创建时所对应的 Token。如果你轮换了 Token 但未妥善保存旧 Token，一旦需要灾难恢复，将面临无法解密的困境，导致集群彻底无法恢复。

总结

Server Token 轮换是 RKE2 集群安全运维的必要环节，但也是一项高风险操作。

  • 充分准备：在测试环境演练，备份集群数据、配置文件和所有历史 Token。
  • 严谨操作：严格遵守“单节点执行命令、逐个更新配置、逐个重启并验证”的顺序。
  • 版本确认：仔细阅读你所用 RKE2 版本的官方文档，确认此功能的状态和潜在问题。