排查kubeadm-ha部署故障的10个常见问题与解决方案

排查kubeadm-ha部署故障的10个常见问题与解决方案【免费下载链接】kubeadm-hakubeadm-ha 使用 kubeadm 进行高可用 kubernetes 集群搭建利用 ansible-playbook 实现自动化安装既提供一键安装脚本也可以根据 playbook 分步执行安装各个组件。项目地址: https://gitcode.com/gh_mirrors/ku/kubeadm-hakubeadm-ha是一款基于kubeadm和ansible-playbook实现的高可用Kubernetes集群自动化部署工具能帮助用户快速搭建稳定可靠的K8s集群。在实际部署过程中新手用户可能会遇到各种问题本文总结了10个最常见的故障及解决方案助你轻松应对部署挑战。1. etcd节点数量非奇数导致初始化失败 ⚠️问题表现执行集群初始化时ansible-playbook报错提示初始化集群时 etcd 节点只能为奇数个。解决方案检查example/hosts.m-master.ip.ini或对应inventory文件中的[etcd]节点组确保etcd节点数量为1、3、5等奇数参考官方文档调整节点配置docs/00-安装须知.md原理etcd集群采用Raft共识算法需要奇数个节点才能保证数据一致性和高可用性。2. kubelet启动失败cgroup驱动不匹配 问题表现kubelet服务状态异常日志中出现failed to run Kubelet: misconfiguration: kubelet cgroup driver错误。解决方案检查容器运行时的cgroup驱动Docker查看/etc/docker/daemon.json中的exec-opts: [native.cgroupdriversystemd]Containerd检查/etc/containerd/config.toml中的SystemdCgroup true统一配置为systemd驱动# 修改kubelet配置 vi /var/lib/kubelet/config.yaml # 设置cgroupDriver: systemd # 修改kubeadm-flags.env如存在 vi /var/lib/kubelet/kubeadm-flags.env # 确保--cgroup-driversystemd # 重启服务 systemctl daemon-reload systemctl restart kubelet配置文件位置roles/prepare/container-engine/tasks/containerd/main.yml3. 证书过期或无效导致API访问失败 问题表现kubectl命令失败提示x509: certificate has expired or is not yet valid。解决方案执行证书轮换剧本ansible-playbook -i example/hosts.m-master.ip.ini 92-certificates-renew.yml自定义证书有效期修改example/variables.yaml中的etcd_certs_expired和etcd_ca_certs_expired参数轮换后重启相关服务systemctl restart docker containerd kubelet官方文档docs/03-证书轮换.md4. 负载均衡配置错误导致节点无法加入集群 问题表现节点加入集群时超时提示connection refused或timeout。解决方案检查负载均衡器状态内部LB确认nginx/haproxy容器运行正常外部LB验证VIP和后端服务健康状态验证apiserver端口可访问性# 在问题节点上执行 nc -z -w 3 {{ kube_apiserver_ip }} {{ lb_kube_apiserver_port }}检查LB配置文件roles/load-balancer/templates/nginx/nginx.conf.j2负载模式说明docs/00-安装须知.md中的Kube-apiserver负载模式部分5. 节点资源不足导致组件启动失败 问题表现pod状态为Pending或CrashLoopBackOffdescribe显示Insufficient memory或Insufficient CPU。解决方案检查节点资源使用情况kubectl top nodes确保节点满足最低硬件要求Master节点至少2CPU、4GB内存Worker节点至少2CPU、2GB内存调整资源紧张的pod资源请求修改对应deployment的resources配置初始化检查roles/prepare/base/tasks/verify_node.yml6. 网络插件安装失败导致节点NotReady 问题表现节点状态长时间为NotReady网络插件podcalico/flannel启动失败。解决方案检查网络插件pod状态kubectl get pods -n kube-system查看插件日志排查具体错误kubectl logs pod-name -n kube-system重新部署网络插件ansible-playbook -i example/hosts.m-master.ip.ini 21-network-plugin.yml网络插件配置roles/plugins/network-plugins/tasks/main.yml7. 防火墙或SELinux阻止组件通信 问题表现服务间通信失败日志中出现connection refused但服务已正常启动。解决方案检查防火墙状态并开放必要端口# 查看开放端口 firewall-cmd --list-ports # 开放K8s所需端口参考官方文档 firewall-cmd --add-port6443/tcp --permanent firewall-cmd --add-port2379-2380/tcp --permanent firewall-cmd --reload临时关闭SELinuxsetenforce 0永久禁用SELinux修改/etc/selinux/config设置SELINUXdisabled端口要求docs/00-安装须知.md中的网络要求部分8. 添加etcd节点失败集群状态不一致 问题表现执行添加etcd节点剧本后新节点未加入集群或同步失败。解决方案确保一次只添加一个etcd节点docs/02/添加 etcd 节点.md检查新节点是否已在集群中# 在现有etcd节点执行 etcdctl member list \ --cacert/etc/kubernetes/pki/etcd/ca.crt \ --key/etc/kubernetes/pki/etcd/healthcheck-client.key \ --cert/etc/kubernetes/pki/etcd/healthcheck-client.crt手动添加节点如自动添加失败etcdctl member add etcd-new-node https://new-node-ip:2380 \ --cacert/etc/kubernetes/pki/etcd/ca.crt \ --key/etc/kubernetes/pki/etcd/healthcheck-client.key \ --cert/etc/kubernetes/pki/etcd/healthcheck-client.crt添加etcd角色roles/etcd/install/tasks/main.yml9. 集群升级失败版本不兼容 问题表现执行升级剧本后部分组件版本不匹配或启动失败。解决方案检查升级前集群健康状态kubectl get nodes和kubectl get pods -n kube-system确保升级版本符合Kubernetes版本 skew策略控制平面组件间最多差一个小版本重新执行升级剧本ansible-playbook -i example/hosts.m-master.ip.ini 91-upgrade-cluster.yml升级后验证节点版本kubectl get nodes升级流程roles/upgrade/tasks/main.yml10. 节点删除后资源残留导致重新加入失败 ♻️问题表现删除节点后重新添加时提示node already exists或证书相关错误。解决方案彻底清理节点ansible-playbook -i example/hosts.m-master.ip.ini 99-reset-cluster.yml --limitnode-name手动清理残留数据如重置脚本未完全清理# 停止服务 systemctl stop kubelet containerd docker # 清理文件 rm -rf /etc/cni/net.d /var/lib/kubelet /var/lib/etcd \ /etc/kubernetes /var/lib/cni /var/run/kubernetes # 重启节点 reboot从集群中删除节点对象kubectl delete node node-name节点删除流程roles/remove/node/tasks/main.yml总结与预防措施 ️kubeadm-ha部署过程中遇到的大多数问题都与环境配置、资源不足或网络问题相关。为避免这些常见问题部署前仔细阅读docs/00-安装须知.md确保满足所有软硬件要求使用示例配置文件作为基础进行修改example/variables.yaml定期备份集群状态ansible-playbook -i example/hosts.m-master.ip.ini 93-backup-cluster.yml关注证书有效期提前进行轮换通过本文介绍的解决方案大多数部署问题都能得到快速解决。如遇到复杂问题可查阅项目完整文档或在社区寻求帮助。【免费下载链接】kubeadm-hakubeadm-ha 使用 kubeadm 进行高可用 kubernetes 集群搭建利用 ansible-playbook 实现自动化安装既提供一键安装脚本也可以根据 playbook 分步执行安装各个组件。项目地址: https://gitcode.com/gh_mirrors/ku/kubeadm-ha创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考