Kubespray Troubleshooting 是一个针对 Kubespray 部署失败的排障技能条目，目标是在 playbook 失败、kubeadm join 报错、etcd 健康检查超时、节点 NotReady、证书异常等情况下给出定位步骤与修复命令。其核心原则是：先读取失败的具体任务名称，再到该节点查看日志，修复后重新运行；Ansible 具备幂等性，因此可安全重跑。
适用场景：部署过程中 playbook 中断；kubeadm join 失败；etcd 健康检查超时；节点长期处于 NotReady；证书相关错误；容器运行时异常；inventory 配置或路径问题。资料明确说明不适用于初始部署搭建、集群升级与证书续期，这些应使用对应的其他技能。
主要排障路径：资料给出按任务类型分流的快速诊断流程——etcd 任务失败时查看 etcd 日志（journalctl -u etcd -f）；kubeadm join 失败时核对 inventory 中的 ip= 配置；container-engine 任务失败时检查 containerd 状态（systemctl status containerd）；download 任务失败时检查网络与代理；任意任务可用 -vvv 获取 Ansible 调试输出。
典型问题与处理：VirtualBox NAT IP 场景下出现连接 10.0.2.15:6443 被拒，原因是 Kubespray 识别到了 NAT 接口而非 host-only 网络，需在 inventory 中显式指定 ip=，如 k8s-ctr ansible_host=192.168.10.10 ip=192.168.10.10；若已用错误 IP 部署，需先执行 reset.yml 再重新 cluster.yml。etcd 健康检查失败时，可在 etcd 节点查看服务状态与日志、用 ss -tlnp | grep 2379 确认监听，常见原因包括 etcd 配置 IP 错误、证书不匹配（检查 /etc/ssl/etcd/ssl/ 权限）、防火墙阻断 2379/2380 端口；状态陈旧时同样通过 reset 后重部署解决。节点 NotReady 时检查 kubelet 状态与日志、CNI 目录 /etc/cni/net.d/ 与 /opt/cni/bin/、节点 conditions，常见原因包括 CNI 未安装、containerd 未运行、kubelet 配置有误。出现 no hosts matched 时，应使用 inventory 文件路径而非目录，并用 ansible -i ... --list-hosts 验证解析。容器运行时报 CRI 连接失败时，检查 containerd 状态与日志、重启服务并确认 /var/run/containerd/containerd.sock 存在。证书过期或未生效时，可用 kubeadm certs check-expiration 与 openssl 查看证书日期，续期流程参见证书相关技能。
重置与重跑：部署损坏严重时可执行 ansible-playbook -i inventory/mycluster/inventory.ini reset.yml -b，按提示输入 yes 确认；重置会删除 etcd 数据，导致全部集群状态丢失。重置后可检查 kubelet 是否 inactive、/etc/kubernetes/ 是否已清空或最小化，再执行 cluster.yml 重新部署。修复后可完整重跑，或仅重跑特定 tags（如 --tags etcd、--tags network）。
日志位置：etcd 用 journalctl -u etcd，kubelet 用 journalctl -u kubelet，containerd 用 journalctl -u containerd，API server 用 kubectl logs -n kube-system kube-apiserver-<node>，Ansible 可加 -vvv 输出调试信息。
限制：资料未提供该技能的安装方式、收费模式、支持的 Kubespray/Kubernetes 版本范围与平台细节，这些事实暂未提供。