1. K3S节点添加失败问题概述

最近在部署K3S集群时遇到了节点添加失败的问题，错误提示为"Node password rejected, duplicate hostname or contents of '/etc/rancher/node/password' may not match server node-passwd entry"。这个问题在K3S集群部署中相当常见，特别是当我们需要扩展集群规模时。K3S作为轻量级的Kubernetes发行版，虽然简化了很多部署流程，但在节点管理方面仍然有一些需要注意的细节。

2. 错误原因深度分析

2.1 主机名冲突问题

K3S集群中的每个节点都必须有唯一的主机名。如果尝试添加的新节点与已有节点主机名重复，就会触发这个错误。这种情况在以下场景特别容易出现：

• 使用虚拟机模板快速部署多个节点
• 容器化环境中使用相同的基础镜像
• 自动化部署脚本未正确设置主机名

检查方法很简单，在要添加的节点上执行hostname命令，然后在集群其他节点上执行kubectl get nodes，对比主机名是否重复。

2.2 密码文件不匹配问题

K3S使用/etc/rancher/node/password文件来验证节点身份。这个机制的工作流程是：

1. 首次注册时，agent节点会生成随机密码并存储在本地
2. master节点会记录这个密码到/var/lib/rancher/k3s/server/cred/node-passwd
3. 后续注册时，两边密码必须匹配

常见的不匹配情况包括：

• 节点被卸载后重新安装但保留了旧的password文件
• 手动修改了password文件内容
• 通过VM快照恢复节点导致密码不一致

3. 问题解决方案

3.1 解决主机名冲突

对于主机名冲突问题，有以下几种解决方法：

1. 修改主机名后重新注册

# 在问题节点上执行 sudo hostnamectl set-hostname new-unique-name sudo systemctl restart k3s-agent

2. 使用--with-node-id参数

curl -sfL https://get.k3s.io | K3S_URL=https://server-url:6443 \ K3S_TOKEN=mytoken sh -s - --with-node-id

这个参数会在主机名后附加随机ID，确保唯一性。

3.2 解决密码不匹配问题

对于密码文件不匹配的情况，可以采取以下步骤：

1. 清理旧密码文件

sudo rm -f /etc/rancher/node/password sudo systemctl restart k3s-agent

2. 手动同步密码

# 在master节点上查看记录的密码 sudo cat /var/lib/rancher/k3s/server/cred/node-passwd # 在agent节点上创建匹配的密码文件 echo "your-password-here" | sudo tee /etc/rancher/node/password

3. 完全重新安装节点

# 先卸载 /usr/local/bin/k3s-agent-uninstall.sh # 然后重新安装 curl -sfL https://get.k3s.io | K3S_URL=https://server-url:6443 \ K3S_TOKEN=mytoken sh -

4. 高级排查技巧

4.1 日志分析

当遇到节点添加问题时，查看日志是最直接的排查方法：

Master节点日志

journalctl -u k3s -f

Agent节点日志

journalctl -u k3s-agent -f

关键日志信息包括：

• "Node password rejected"：密码不匹配
• "duplicate hostname"：主机名冲突
• "failed to join cluster"：网络连接问题

4.2 网络连接检查

确保节点间的网络连通性：

# 检查6443端口连通性 telnet master-ip 6443 # 检查节点间UDP通信(8472端口) nc -uz master-ip 8472

4.3 使用调试模式

对于复杂问题，可以启用调试模式获取更详细日志：

# Master节点 curl -sfL https://get.k3s.io | sh -s - --debug # Agent节点 curl -sfL https://get.k3s.io | K3S_URL=https://server-url:6443 \ K3S_TOKEN=mytoken sh -s - --debug

5. 预防措施与最佳实践

5.1 节点命名规范

建议采用有意义的命名规则，例如：

• 按功能划分：k3s-master-01, k3s-worker-01
• 按区域划分：k3s-us-east-1a-01
• 包含环境标识：k3s-prod-db-01

5.2 自动化部署建议

使用Terraform或Ansible等工具部署时，确保：

resource "null_resource" "k3s_agent" { provisioner "remote-exec" { inline = [ "hostnamectl set-hostname ${var.node_name}", "curl -sfL https://get.k3s.io | K3S_URL=https://${var.master_ip}:6443 K3S_TOKEN=${var.token} sh -s - --with-node-id" ] } }

5.3 密码管理策略

对于生产环境，建议：

1. 集中管理password文件内容
2. 定期轮换节点凭证
3. 使用配置管理工具同步密码

6. 其他常见相关问题

6.1 证书过期问题

如果节点长时间离线后重新加入，可能会遇到证书过期问题。解决方法：

# 在master节点上 k3s certificate rotate

6.2 资源不足问题

节点添加失败也可能是资源不足导致的，检查：

kubectl describe node <node-name>

关注CPU、内存和Pod可用数量。

6.3 内核参数检查

确保节点满足K3S的最低要求：

# 检查conntrack模块 lsmod | grep conntrack # 检查网络转发设置 cat /proc/sys/net/ipv4/ip_forward

7. 实际案例分享

最近在客户环境遇到一个典型案例：客户使用VMware模板部署了多个K3S节点，添加节点时持续报错。经过排查发现：

1. 所有VM都继承了模板的主机名
2. 快照恢复导致password文件不一致

解决方案：

1. 在模板中设置随机主机名

echo "k3s-node-$(openssl rand -hex 3)" > /etc/hostname

2. 部署后自动清理password文件
3. 使用--with-node-id参数确保唯一性

8. 性能优化建议

对于大规模集群，节点添加性能也很关键：

1. 调整kubelet参数

# /etc/rancher/k3s/config.yaml kubelet-arg: - "serialize-image-pulls=false" - "max-pods=250"

2. 优化etcd配置

# /etc/rancher/k3s/config.yaml etcd-expose-metrics: true etcd-snapshot-retention: 5

3. 网络插件调优

# /etc/rancher/k3s/config.yaml flannel-backend: host-gw

9. 监控与告警配置

建议配置以下监控指标：

1. 节点添加成功率
2. 节点心跳间隔
3. 证书有效期

使用Prometheus的示例配置：

- job_name: 'k3s-nodes' metrics_path: '/metrics' static_configs: - targets: ['k3s-master:6443']

10. 总结与个人经验

在实际运维K3S集群的过程中，节点管理是最常见的操作之一。根据我的经验，以下几点特别重要：

1. 主机名唯一性是基础中的基础，在自动化部署流程中必须确保
2. password文件机制虽然简单，但在节点重建时容易出问题，需要特别注意
3. 日志是最直接的排查手段，遇到问题先看日志
4. 生产环境建议使用--with-node-id参数，可以避免很多奇怪的问题

最后分享一个小技巧：在节点初始化脚本中加入延时，可以避免批量添加节点时的并发问题：

sleep $((RANDOM % 30)) # 随机延时0-30秒