企业官网建设流程全解析

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

【免费下载链接】kubeadm-hakubeadm-ha 使用 kubeadm 进行高可用 kubernetes 集群搭建，利用 ansible-playbook 实现自动化安装，既提供一键安装脚本，也可以根据 playbook 分步执行安装各个组件。项目地址: https://gitcode.com/gh_mirrors/ku/kubeadm-ha

kubeadm-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"错误。

解决方案：

1. 检查容器运行时的cgroup驱动：

   • Docker：查看/etc/docker/daemon.json中的"exec-opts": ["native.cgroupdriver=systemd"]
   • Containerd：检查/etc/containerd/config.toml中的SystemdCgroup = true

2. 统一配置为systemd驱动：

   # 修改kubelet配置 vi /var/lib/kubelet/config.yaml # 设置cgroupDriver: systemd # 修改kubeadm-flags.env（如存在） vi /var/lib/kubelet/kubeadm-flags.env # 确保--cgroup-driver=systemd # 重启服务 systemctl daemon-reload systemctl restart kubelet

配置文件位置：roles/prepare/container-engine/tasks/containerd/main.yml

3. 证书过期或无效导致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-证书轮换.md

4. 负载均衡配置错误导致节点无法加入集群 🔄

问题表现：节点加入集群时超时，提示"connection refused"或"timeout"。

解决方案：

1. 检查负载均衡器状态：

   • 内部LB：确认nginx/haproxy容器运行正常
   • 外部LB：验证VIP和后端服务健康状态

2. 验证apiserver端口可访问性：

   # 在问题节点上执行 nc -z -w 3 {{ kube_apiserver_ip }} {{ lb_kube_apiserver_port }}

3. 检查LB配置文件：roles/load-balancer/templates/nginx/nginx.conf.j2

负载模式说明：docs/00-安装须知.md中的"Kube-apiserver负载模式"部分

5. 节点资源不足导致组件启动失败 📊

问题表现：pod状态为Pending或CrashLoopBackOff，describe显示"Insufficient memory"或"Insufficient CPU"。

解决方案：

• 检查节点资源使用情况：kubectl top nodes
• 确保节点满足最低硬件要求：
  • Master节点：至少2CPU、4GB内存
  • Worker节点：至少2CPU、2GB内存
• 调整资源紧张的pod资源请求：修改对应deployment的resources配置

初始化检查：roles/prepare/base/tasks/verify_node.yml

6. 网络插件安装失败导致节点NotReady 🔌

问题表现：节点状态长时间为NotReady，网络插件pod（calico/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.yml

7. 防火墙或SELinux阻止组件通信 🔥

问题表现：服务间通信失败，日志中出现"connection refused"但服务已正常启动。

解决方案：

• 检查防火墙状态并开放必要端口：

  # 查看开放端口 firewall-cmd --list-ports # 开放K8s所需端口（参考官方文档） firewall-cmd --add-port=6443/tcp --permanent firewall-cmd --add-port=2379-2380/tcp --permanent firewall-cmd --reload

• 临时关闭SELinux：

  setenforce 0

• 永久禁用SELinux：修改/etc/selinux/config，设置SELINUX=disabled

端口要求：docs/00-安装须知.md中的"网络要求"部分

8. 添加etcd节点失败：集群状态不一致 📌

问题表现：执行添加etcd节点剧本后，新节点未加入集群或同步失败。

解决方案：

1. 确保一次只添加一个etcd节点：docs/02/添加 etcd 节点.md

2. 检查新节点是否已在集群中：

   # 在现有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

3. 手动添加节点（如自动添加失败）：

   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.yml

9. 集群升级失败：版本不兼容 🆙

问题表现：执行升级剧本后，部分组件版本不匹配或启动失败。

解决方案：

• 检查升级前集群健康状态：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.yml

10. 节点删除后资源残留导致重新加入失败 ♻️

问题表现：删除节点后重新添加时，提示"node already exists"或证书相关错误。

解决方案：

1. 彻底清理节点：

   ansible-playbook -i example/hosts.m-master.ip.ini 99-reset-cluster.yml --limit=<node-name>

2. 手动清理残留数据（如重置脚本未完全清理）：

   # 停止服务 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

3. 从集群中删除节点对象：

   kubectl delete node <node-name>

节点删除流程：roles/remove/node/tasks/main.yml

总结与预防措施 🛡️

kubeadm-ha部署过程中遇到的大多数问题都与环境配置、资源不足或网络问题相关。为避免这些常见问题：

1. 部署前仔细阅读docs/00-安装须知.md，确保满足所有软硬件要求
2. 使用示例配置文件作为基础进行修改：example/variables.yaml
3. 定期备份集群状态：ansible-playbook -i example/hosts.m-master.ip.ini 93-backup-cluster.yml
4. 关注证书有效期，提前进行轮换

通过本文介绍的解决方案，大多数部署问题都能得到快速解决。如遇到复杂问题，可查阅项目完整文档或在社区寻求帮助。

【免费下载链接】kubeadm-hakubeadm-ha 使用 kubeadm 进行高可用 kubernetes 集群搭建，利用 ansible-playbook 实现自动化安装，既提供一键安装脚本，也可以根据 playbook 分步执行安装各个组件。项目地址: https://gitcode.com/gh_mirrors/ku/kubeadm-ha