Debian环境下Kubernetes安装常见问题

Debian 环境下 Kubernetes 安装常见问题与排查

一 环境准备与前置条件

• 操作系统建议使用 Debian 10+，各节点时间同步（可用 NTP），并确保主机名与 IP 映射正确（/etc/hosts 或 DNS）。
• 关闭 Swap：执行 sudo swapoff -a，并在 /etc/fstab 中注释 swap 行，避免 kubelet 启动失败。
• 加载内核模块并设置 sysctl：
  • 模块：overlay、br_netfilter
  • 参数：net.bridge.bridge-nf-call-iptables = 1、net.ipv4.ip_forward = 1
• 容器运行时：安装并启用 containerd（或 Docker）。以 containerd 为例：
  • 安装：sudo apt install -y containerd
  • 启用：sudo systemctl enable --now containerd
• 资源建议：单节点至少 2 核 CPU、2GB 内存、20GB 磁盘，否则易出现调度或组件异常。

二 组件安装与仓库配置

• 更新索引并安装依赖：sudo apt update && sudo apt install -y apt-transport-https ca-certificates curl
• 添加 Kubernetes APT 源并安装组件：
  • 源：echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
  • 安装：sudo apt install -y kubelet kubeadm kubectl
  • 锁定版本：sudo apt-mark hold kubelet kubeadm kubectl（避免被系统升级干扰）
• 容器运行时选择：如使用 Docker，需同时安装 docker-ce、docker-ce-cli、containerd.io 并启动服务。

三 初始化与网络插件

• 初始化控制平面（示例）：sudo kubeadm init --pod-network-cidr=10.244.0.0/16（Flannel 常用该网段）。
• 配置 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 init 输出中的 kubeadm join ... 命令，包含 token 与 –discovery-token-ca-cert-hash sha256:。
• 验证：kubectl cluster-info、kubectl get nodes 应显示控制平面与节点 Ready。

四 高频错误与快速修复

• 节点 NotReady
  • 检查网络插件是否成功部署：kubectl get pods -n kube-system，若 CrashLoopBackOff/Error，查看日志：kubectl logs -n kube-system <pod>。
  • 确认 CNI 网段与控制平面 --pod-network-cidr 一致（如 Flannel 默认 10.244.0.0/16）。
• kubelet 启动失败
  • 确认 Swap 已关闭 且 /etc/fstab 无 swap 挂载。
  • 检查容器运行时：sudo systemctl status containerd（或 docker），异常时 journalctl -u containerd -xe 查看。
  • 确认内核参数与模块已生效：sysctl net.bridge.bridge-nf-call-iptables、lsmod | grep br_netfilter。
• 端口被占用或访问异常
  • 放行关键端口：6443（APIServer）、2379/2380（etcd）、以及 kubelet 健康端口等；云厂商安全组与主机防火墙需同步放通。
• 镜像拉取失败
  • 配置镜像加速（如 Docker：/etc/docker/daemon.json 添加加速器地址），或导入离线镜像。
• 节点无法加入集群
  • 核对 token 有效期 与 CA 证书哈希，必要时 kubeadm token create --print-join-command 重新生成加入命令。
• CoreDNS 解析异常
  • 确认 kube-dns/CoreDNS 已 Running：kubectl get pods -n kube-system -l k8s-app=coredns；检查 Service 与 Endpoints 是否就绪。
• 版本不兼容
  • 保持 kubelet/kubeadm/kubectl 版本一致，并与目标 Kubernetes 版本 匹配，参考官方兼容矩阵。

五 实用命令清单

• 系统与服务：sudo systemctl status kubelet、sudo journalctl -u kubelet -xe、tail -f /var/log/syslog、dmesg
• 集群状态：kubectl cluster-info、kubectl get nodes -o wide、kubectl get pods -A
• 组件日志：kubectl logs -n kube-system <pod> -c <container>
• 网络连通性：ping <目标IP>、nc -vz <IP> <端口>
• 资源与重启：top、free -m、sudo systemctl restart containerd