Debian上Kubernetes部署有哪些常见问题及解决方案

Debian上Kubernetes部署常见问题与解决方案

一 环境准备与依赖

• 基础要求：至少2核CPU、2GB内存、20GB磁盘（生产建议更高）；系统更新：sudo apt update && sudo apt upgrade -y。容器运行时建议安装Docker或containerd并启动：sudo systemctl start docker && sudo systemctl enable docker。必须禁用Swap：sudo swapoff -a 并注释 /etc/fstab 中的 swap 行。添加 Kubernetes APT 源并安装组件：sudo apt install -y kubelet kubeadm kubectl 后执行 sudo apt-mark hold kubelet kubeadm kubectl 防止意外升级。初始化时指定 Pod 网段，例如 Flannel 常用 10.244.0.0/16：sudo kubeadm init --pod-network-cidr=10.244.0.0/16；完成后配置 kubectl：mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config。最后部署网络插件（如 Flannel）：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml。

二 常见故障与修复

• 节点无法加入集群（kubeadm join 失败）：常见原因为Token 过期、网络不通、防火墙阻断。在主节点重新生成加入命令：sudo kubeadm token create --print-join-command；在工作节点执行输出的 join 命令。开放必要端口（示例 UFW）：sudo ufw allow 6443/tcp, 2379/tcp, 2380/tcp；确保节点间可 ping <master-ip> 且安全组/物理防火墙放行。
• Pod 无法启动（ImagePullBackOff/CrashLoopBackOff）：先用 kubectl describe pod <pod> 与 kubectl logs <pod> 定位；若镜像不存在或拉取受限，手动在节点上 docker pull <image> 验证；检查资源是否不足并补充 resources.requests/limits；确认容器运行时与镜像仓库凭据配置正确。
• 节点 NotReady 或 Pod 间不通：多因网络插件未安装/异常或节点未加入同一网络。执行 kubectl get pods -n kube-system | grep -E 'flannel|calico|kube-proxy' 确认运行；必要时重装网络插件；在 Pod 内 ping <other-pod-ip> 验证连通性；检查节点是否设置了正确的 –node-ip 与路由/桥接。
• CoreDNS 解析失败：检查 CoreDNS Pod 状态与日志：kubectl get pods -n kube-system | grep coredns、kubectl logs -n kube-system <coredns-pod>；核对 kube-system/coredns ConfigMap 的 forward 规则与上游 DNS；确保网络插件正确转发 DNS 流量。
• kubelet 异常（无法启动/频繁重启）：查看状态与日志：sudo systemctl status kubelet、sudo journalctl -u kubelet -f；核对 /var/lib/kubelet/config.yaml 中 clusterDNS/clusterDomain 等；若容器运行时异常或端口冲突，先恢复容器运行时再重启 kubelet。
• 镜像拉取错误（ImagePullBackOff）：核对镜像名与标签、仓库可达性；若使用私有仓库，创建 imagePullSecret 并在 Pod/ServiceAccount 中引用；必要时配置节点级镜像加速或代理。
• 资源不足导致调度失败（Pending）：用 kubectl top nodes 与 kubectl describe pod <pod> 查看瓶颈；释放节点资源或扩容；为关键负载设置合理的 requests/limits 以避免被 OOM/Kill。

三 网络与安全配置

• 端口与连通性：确保节点间与对外服务所需端口开放，常见包括 6443（API Server）、2379/2380（etcd）、10250/10255（kubelet）、10251/10252（kube-scheduler/controller-manager）、以及 NodePort 范围 30000–32767。使用 ufw/iptables 或云安全组放行，并验证 ping/nc/curl 可达性。
• 时间同步：集群节点需时间同步（建议使用 NTP/chrony），否则可能出现证书校验、调度与 etcd 异常。
• 防火墙与安全组：统一在主机与云平台层放行上述端口；避免阻断 veth/bridge 与 CNI 网段通信。
• 安全加固：确保 TLS 证书有效、RBAC 最小权限、kubeconfig 权限正确（chown $(id -u):$(id -g) $HOME/.kube/config）；避免使用过时的 API 与弱凭据。

四 存储与持久化

• 快速 NFS 示例：在 NFS 服务器（Debian）安装并导出目录：sudo apt install nfs-kernel-server -y，echo "/data/nfs-server *(rw,async,no_subtree_check)" | sudo tee -a /etc/exports，sudo systemctl start nfs-kernel-server && sudo systemctl enable nfs-kernel-server。在集群中创建 PV/PVC（示例 accessModes: ReadWriteMany）并绑定使用。
• 动态供给与 Ceph：使用 Rook 在 Kubernetes 上部署 Ceph 集群，先部署 Rook Operator，再创建 CephCluster 与 StorageClass 实现动态卷供给；安装 ceph-common 以便节点使用 RBD/cephfs。
• PVC 处于 Pending：检查 StorageClass 是否存在且可用、后端存储健康、PV 容量/访问模式匹配；查看 kubectl get pv,pvc,storageclass 与事件，定位绑定失败原因。

五 日志与快速排查命令清单

• 集群状态：kubectl get nodes、kubectl get pods -A、kubectl get events --sort-by=.metadata.creationTimestamp。
• Pod 诊断：kubectl describe pod <pod> -n <ns>、kubectl logs <pod> [-c <container>] [--previous]、kubectl exec -it <pod> -n <ns> -- sh。
• 组件日志：sudo journalctl -u kubelet -f、sudo journalctl -u kube-apiserver -f（如部署为 systemd 单元）。
• 网络连通：在 Pod 内 ping <pod-ip>/<svc-clusterip>、nslookup <svc-name>.<ns>.svc.cluster.local；节点间 ping/nc/curl 验证 API 与 NodePort 可达性。
• 资源与调度：kubectl top nodes、kubectl top pods -A、kubectl describe node <node> 查看 Allocatable/Allocated 与污点/容忍度。
• 配置与权限：kubectl config view、ls -l $HOME/.kube/config、kubectl get rolebinding,clusterrolebinding --all-namespaces。