k3s-ansible故障排查手册：10个常见问题及解决方案

【免费下载链接】k3s-ansible 项目地址: https://gitcode.com/gh_mirrors/k3s/k3s-ansible

k3s-ansible是一款简化Kubernetes集群部署与管理的工具，通过Ansible自动化脚本帮助用户快速搭建轻量级K3s集群。本文整理了使用过程中最常见的10个技术问题及解决方案，帮助新手用户快速定位并解决部署难题。

1. iptables版本兼容性问题

问题表现：K3s服务启动失败，日志中出现iptables相关错误

解决方案：

• iptables v1.8.0-1.8.4存在已知兼容性问题(roles/prereq/tasks/main.yml#L267)
• Debian/Ubuntu系统：通过update-alternatives切换到iptables-legacy
• Raspbian系统：强制使用iptables-legacy替代nftables(roles/raspberrypi/tasks/prereq/Raspbian.yml#L24)

2. 服务器升级时的etcd问题

问题表现：升级K3s服务器节点后集群无法启动

解决方案：

• 必须按顺序重启服务器节点，避免etcd learner问题(playbooks/upgrade.yml#L3)
• 升级命令示例：ansible-playbook playbooks/upgrade.yml
• 每次只升级一个服务器节点，等待完全启动后再升级下一个

3. 空气间隙环境下的镜像拉取超时

问题表现：离线环境部署时镜像拉取失败

解决方案：

• 调整Ansible任务超时时间(roles/airgap/tasks/main.yml#L29)
• 提前下载并分发K3s镜像到所有节点
• 配置私有镜像仓库并在inventory文件中指定

4. Ubuntu系统中的VXLan配置问题

问题表现：节点间网络通信异常，Pod跨节点无法通信

解决方案：

• 应用Ubuntu特定网络修复(roles/raspberrypi/tasks/prereq/Ubuntu.yml#L22)
• 检查并启用IP转发：sysctl net.ipv4.ip_forward=1
• 验证VXLan模块加载：lsmod | grep vxlan

5. K3s服务启动超时

问题表现：Ansible任务报告"timeout"错误，K3s服务未正常启动

解决方案：

• 延长服务启动超时时间(roles/k3s_server/tasks/main.yml#L91)
• 检查系统资源：确保节点有足够的CPU和内存
• 查看详细日志：journalctl -u k3s.service -f

6. 节点加入集群失败

问题表现：agent节点无法连接到server节点

解决方案：

• 检查token是否正确：验证inventory文件中的token配置
• 确保网络连通性：服务器节点6443端口是否开放
• 检查防火墙规则：允许K3s所需端口通过

7. Ansible环境变量警告

问题表现：执行playbook时出现"ansible-lint"环境变量警告

解决方案：

• 这是已知的lint工具误报(roles/k3s_server/tasks/main.yml#L105)
• 可以安全忽略此类警告
• 如需消除警告，可更新ansible-lint到最新版本

8. 树莓派重启后节点无法恢复

问题表现：树莓派节点重启后无法重新加入集群

解决方案：

• 检查重启超时设置(roles/raspberrypi/handlers/main.yml#L5)
• 确保K3s服务设置为开机自启：systemctl enable k3s
• 检查SD卡健康状态，避免因存储问题导致的启动失败

9. 空气间隙环境下文件缺失

问题表现：离线部署时报"file not found"错误

解决方案：

• 确认所有必需文件已复制到节点(roles/airgap/tasks/main.yml#L57)
• 检查文件权限：确保K3s可执行文件有执行权限
• 验证文件完整性：比对文件哈希值

10. 集群重置后重新部署失败

问题表现：执行reset.yml后再次部署集群失败

解决方案：

• 彻底清理残留文件：ansible-playbook playbooks/reset.yml
• 检查etcd数据目录是否完全清除
• 确保所有节点时间同步：使用NTP服务

故障排查工具推荐

1. K3s日志查看：journalctl -u k3s.service 或 journalctl -u k3s-agent.service
2. 集群状态检查：kubectl get nodes 和 kubectl get pods -A
3. Ansible详细输出：ansible-playbook -vvv playbooks/site.yml

遇到其他问题时，可以查阅项目issue跟踪系统(galaxy.yml#L62)或检查官方文档获取最新解决方案。定期更新k3s-ansible到最新版本也是避免已知问题的有效方法。

【免费下载链接】k3s-ansible 项目地址: https://gitcode.com/gh_mirrors/k3s/k3s-ansible