Debian系统Kubernetes安装常见问题及解决方法

1. 网络配置问题

常见表现：节点间无法通信、kubectl get nodes显示节点状态为NotReady、镜像拉取失败。
解决方法：

确保所有节点之间网络连接稳定，可通过ping <node-ip>测试连通性；
检查防火墙设置，开放Kubernetes必需端口（如API Server端口6443、etcd端口2379/2380、kubelet端口10250/10255等），例如使用ufw命令：sudo ufw allow 6443/tcp; sudo ufw allow 2379/tcp; sudo ufw allow 2380/tcp；
配置kubelet服务，确保其监听正确地址：编辑/etc/systemd/system/kubelet.service.d/10-kubeadm.conf，添加--node-ip=<node-ip>参数；
验证网络插件（如Flannel）是否正常运行：kubectl get pods -n kube-system | grep kube-proxy，若未运行，可尝试重新安装网络插件。

2. 资源不足问题

常见表现：安装过程中提示“Insufficient resources”（资源不足）、Pod无法调度（Pending状态）。
解决方法：

检查节点资源使用情况：使用free -h查看内存、df -h查看磁盘空间、top查看CPU负载；
关闭不必要的进程释放资源，或增加节点（如添加Worker节点）；

调整Pod资源请求和限制，在Deployment配置中设置合理的resources.requests和resources.limits，例如：

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

3. 依赖与安装包问题

常见表现：E: Unable to locate package kubeadm（找不到kubeadm包）、kubeadm安装失败。
解决方法：

更新包列表：sudo apt-get update；
安装必要依赖：sudo apt-get install -y apt-transport-https curl software-properties-common；

正确添加Kubernetes APT仓库：

curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt update

安装kubelet、kubeadm、kubectl：sudo apt install -y kubelet kubeadm kubectl，并锁定版本（避免自动升级）：sudo apt-mark hold kubelet kubeadm kubectl。

4. 版本兼容性问题

常见表现：kubeadm version is not supported（kubeadm版本不兼容）、组件启动失败。
解决方法：

参考Kubernetes官方文档的版本兼容性矩阵，确保kubelet、kubeadm、kubectl版本一致，且与Debian版本兼容（如Debian 11/12支持Kubernetes 1.26+）；

若版本不兼容，降级或升级Kubernetes组件至兼容版本，例如：

sudo apt install -y kubelet=<version> kubeadm=<version> kubectl=<version>
sudo apt-mark hold kubelet kubeadm kubectl

5. 权限问题

常见表现：执行kubeadm init或kubectl命令时提示“Permission denied”（权限不足）。
解决方法：

使用sudo运行命令，例如：sudo kubeadm init；
若需普通用户执行kubectl，将用户加入sudoers文件：sudo visudo，添加<username> ALL=(ALL) NOPASSWD:ALL；
配置kubeconfig文件权限：sudo chown $(id -u):$(id -g) $HOME/.kube/config。

6. 配置文件错误

常见表现：Invalid configuration: no servers are available（无效配置，无可用服务器）、kubectl无法连接集群。
解决方法：

检查kubeconfig文件路径和内容是否正确，默认路径为$HOME/.kube/config，可使用kubectl config view查看当前配置；
确保kubeconfig中的clusters.server字段指向正确的API Server地址（如https://<master-ip>:6443）；
若配置文件损坏，可重新生成：删除旧配置并重新运行kubeadm init，再复制新的admin.conf文件。

7. 日志分析与排查

常见表现：安装或运行过程中出现未知错误，无法定位原因。
解决方法：

使用journalctl查看系统组件日志，例如：

sudo journalctl -u kubelet -f  # 实时查看kubelet日志
sudo journalctl -u kube-apiserver -f  # 查看API Server日志

使用kubectl logs查看Pod日志，例如：

kubectl logs -n kube-system <pod-name>  # 查看指定Pod日志

根据日志中的错误信息（如镜像拉取失败、端口冲突）针对性解决。

8. 节点加入问题

常见表现：工作节点无法加入集群，提示“Token expired”（令牌过期）或“Discovery token CA cert hash mismatch”（CA证书哈希不匹配）。
解决方法：

在主节点重新生成加入命令：sudo kubeadm token create --print-join-command，获取新的token和discovery-token-ca-cert-hash；
在工作节点执行新的加入命令：sudo kubeadm join <master-ip>:6443 --token <new-token> --discovery-token-ca-cert-hash sha256:<new-hash>；
若令牌仍无效，可删除工作节点上的kubelet数据并重新加入：sudo rm -rf /etc/kubernetes /var/lib/kubelet，然后再次运行加入命令。

9. SELinux/AppArmor问题

常见表现：kubelet无法启动、Pod无法创建，提示“Permission denied”或“Operation not permitted”。
解决方法：

若启用了SELinux，临时设置为宽松模式：sudo setenforce 0，永久禁用需修改/etc/selinux/config文件（SELINUX=disabled）；
若启用了AppArmor，调整kubelet的AppArmor配置：编辑/etc/apparmor.d/usr.sbin.kubelet，添加必要的权限，或临时禁用：sudo systemctl stop apparmor。

10. 存储问题

常见表现：Pod无法挂载存储卷、PersistentVolumeClaim（PVC）处于Pending状态。
解决方法：

确保存储后端（如NFS、Ceph）已正确配置并可用，例如NFS服务器需安装nfs-kernel-server并导出目录；
检查StorageClass配置是否正确，例如默认的local-path存储类是否启用；
查看PersistentVolume（PV）状态：kubectl get pv，确保存在可用的PV匹配PVC的需求。

Debian系统Kubernetes安装常见问题及解决方法