Debian 上 Kubernetes 安装常见问题与解决
一 环境准备与内核网络
- 关闭 Swap：Kubernetes 不支持启用 Swap 的环境，执行：sudo swapoff -a，并在 /etc/fstab 中注释包含 swap 的行，确保重启后仍保持关闭。
- 加载内核模块与开启转发：
- 写入模块：echo -e “overlay\nbr_netfilter” | sudo tee /etc/modules-load.d/k8s.conf
- 加载模块：sudo modprobe overlay && sudo modprobe br_netfilter
- 开启桥接流量到 iptables：
echo -e “net.bridge.bridge-nf-call-iptables = 1\nnet.bridge.bridge-nf-call-ip6tables = 1\nnet.ipv4.ip_forward = 1” | sudo tee /etc/sysctl.d/k8s.conf
sudo sysctl --system
- 容器运行时：优先使用 containerd；若使用 Docker，需安装 cri-dockerd 适配 CRI。
- 时间同步：确保节点间时间一致（如 timedatectl set-timezone Asia/Shanghai 并启用 NTP），避免证书校验与组件异常。
二 组件安装与版本兼容
- 安装 kubelet/kubeadm/kubectl：
- 添加仓库（示例）：echo “deb https://apt.kubernetes.io/ kubernetes-xenial main” | sudo tee /etc/apt/sources.list.d/kubernetes.list
- 安装并锁定版本：sudo apt update && sudo apt install -y kubelet kubeadm kubectl && sudo apt-mark hold kubelet kubeadm kubectl
- 版本兼容：控制平面与节点组件版本需匹配，遵循 Kubernetes 版本矩阵；升级/回滚时逐组件对齐版本。
- 容器运行时配置：
- containerd：确认 SystemdCgroup 启用（/etc/containerd/config.toml 中 SystemdCgroup = true，随后 systemctl restart containerd）。
- Docker：若使用 Docker，需部署 cri-dockerd，并在 kubeadm 初始化时通过 --cri-socket 指定。
三 初始化与网络插件
- 初始化控制平面：
- 示例：sudo kubeadm init --pod-network-cidr=10.244.0.0/16（Flannel 常用该网段；如使用 Calico，请按其文档设置）。
- 国内环境可指定镜像仓库：–image-repository registry.aliyuncs.com/google_containers。
- 配置 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
- Calico：kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
- 节点就绪：kubectl get nodes 应显示状态为 Ready；如长时间未就绪，优先检查网络插件 Pod 是否 Running。
四 常见报错与快速修复
- Swap 未关闭：kubeadm 预检失败。解决：swapoff -a 并注释 /etc/fstab 中的 swap 行后重启。
- cgroup 驱动不一致：Docker 默认 cgroupfs，kubelet 常用 systemd。解决：统一为 systemd（Docker 启用 systemd cgroup；或按需调整 kubelet 配置并重启）。
- 镜像拉取失败：国内环境常见。解决：使用 --image-repository 指定国内镜像源，或提前 docker pull/ctr 拉取所需镜像并重新打标。
- 端口未放行：控制面与节点间通信被防火墙阻断。解决：放行关键端口（如 6443、2379、2380、10250 等），或测试环境临时关闭防火墙。
- 证书/时间问题：证书校验失败或组件异常。解决：校准系统时间（NTP/时区），必要时清理旧证书后重新 init。
- 节点 NotReady：多为网络插件未就绪。解决：检查 kube-flannel/kube-proxy 的 Pod 日志与事件，确认 Pod 网段与控制平面配置一致。
- kubeconfig 配置错误：kubectl 报找不到或权限不足。解决：确认 $HOME/.kube/config 存在且当前用户有读写权限，或使用 sudo 提升权限。
五 快速排查清单
- 查看系统日志：journalctl -xe、tail -f /var/log/syslog、dmesg，定位服务启动与内核报错。
- 查看组件日志：kubectl logs -n kube-system 与 kubectl describe pod -n kube-system，聚焦 CrashLoopBackOff/ImagePullBackOff/调度失败等事件。
- 连通性测试：节点间 ping/ss/telnet 测试 6443 等关键端口；确认 VPC/安全组/iptables 策略未拦截。
- 资源与系统状态：top/vmstat 检查 CPU/内存/磁盘压力；必要时扩容或减少系统组件资源请求。
- 配置核对：kubectl config view 检查当前上下文与集群信息；核对 kubelet 启动参数、容器运行时套接字与 cgroup 驱动。
