Hetzner-k3s集群中替换故障节点时的密码冲突问题解决方案

问题背景

在使用Hetzner-k3s管理Kubernetes集群时，运维人员可能会遇到需要替换故障节点的情况。按照标准流程，通常会先使用kubectl delete node命令删除故障节点，然后通过Hetzner控制台删除对应的虚拟机，最后重新运行hetzner-k3s create命令创建新节点。然而，这一过程有时会出现新节点无法成功加入集群的问题。

问题现象

当执行上述替换流程后，新节点的k3s-agent服务无法正常启动。通过检查systemctl status k3s-agent日志，会发现如下关键错误信息：

Waiting to retrieve agent configuration; server is not ready: Node password rejected, duplicate hostname or contents of '/etc/rancher/node/password' may not match server node-passwd entry, try enabling a unique node name with the --with-node-id flag

这个错误表明集群中存在密码冲突问题。具体原因是：虽然旧节点已被删除，但主节点上仍然保留着旧节点的密码配置，而新节点生成了新的密码，由于主机名相同，导致认证失败。

问题根源

K3s集群在管理节点时会为每个节点创建一个密码凭证，这些凭证以Kubernetes Secret的形式存储在kube-system命名空间中。当节点被删除时，仅删除节点资源本身是不够的，相关的密码Secret仍然保留在集群中。当新节点使用相同主机名尝试加入时，会因为密码不匹配而被拒绝。

完整解决方案

1. 删除故障节点： 首先使用kubectl delete node <节点名称>命令从集群中移除故障节点。

2. 清理节点密码Secret： 在重新创建节点前，必须手动删除存储在kube-system命名空间中的节点密码Secret。这些Secret的命名模式通常为<节点名称>.node-password.k3s。可以使用以下命令查找并删除：

   kubectl get secrets -n kube-system | grep node-password
   kubectl delete secret <密码Secret名称> -n kube-system
   

3. 删除虚拟机实例： 通过Hetzner控制台删除对应的故障虚拟机。

4. 创建新节点： 最后执行hetzner-k3s create --config ./hetzner-k3s.yml命令创建新节点。此时系统会生成新的密码Secret，新节点能够顺利加入集群。

技术原理深入

K3s使用节点密码机制来确保节点加入集群的安全性。每个节点的密码存储在以下两个位置：

• 节点本地的/etc/rancher/node/password文件
• 集群中的Secret资源

当节点尝试加入集群时，k3s-server会验证这两个位置的密码是否匹配。在节点替换场景中，如果只删除节点而不清理Secret，就会导致密码不匹配的问题。

最佳实践建议

1. 节点命名规范：考虑使用包含时间戳或唯一标识符的节点命名方案，避免完全依赖主机名。

2. 自动化清理：对于经常需要替换节点的环境，可以编写脚本自动完成节点删除和Secret清理的完整流程。

3. 监控验证：在节点替换后，验证新节点的Ready状态和所有Pod的正常调度。

4. 文档记录：团队内部应记录完整的节点替换流程，包括这个关键的Secret清理步骤。

通过遵循上述解决方案和最佳实践，运维团队可以确保在Hetzner-k3s环境中顺利替换故障节点，维护集群的稳定性和可用性。