如何解决Debian上Kubernetes安装冲突

Debian上Kubernetes安装冲突排查与修复

一 常见冲突与快速判定

• 容器运行时冲突：在 Kubernetes ≥1.24 中，内置的 dockershim 已被移除，直接使用 Docker 作为运行时会出现组件无法启动或找不到镜像等问题。判定方式：执行 kubeadm init 报错包含 CRI、dockershim、或镜像拉取失败；或 kubectl get nodes 长时间 NotReady。处理方向：改用 containerd 作为运行时，或安装 cri-dockerd 适配层。
• 版本不匹配：Kubernetes 与容器运行时/依赖组件版本不兼容，常见现象是 kubelet 反复 CrashLoopBackOff、Pod 无法创建。判定方式：执行 kubectl version --short、docker --version 或 crictl version 查看版本；对照兼容矩阵。处理方向：对齐 Kubernetes 与 Docker/containerd 的版本组合。
• 系统参数与网络冲突：未关闭 swap、内核网络参数未就绪、iptables/nftables 混用导致 Pod 网络不通。判定方式：free -h 显示 swap 仍启用；journalctl -u kubelet 报 cgroup、bridge-nf-call-iptables、或端口占用错误；节点间 6443/2379/2380 等端口不通。处理方向：关闭 swap、配置 sysctl、统一 iptables 后端、放通端口。

二 标准化修复流程

1. 清理冲突组件与锁定版本

• 停止并禁用冲突服务：sudo systemctl disable --now docker kubelet
• 卸载冲突包（按需）：sudo apt remove --purge docker.io docker-ce docker-ce-cli containerd.io
• 安装并启用 containerd（推荐）：sudo apt install -y containerd；生成默认配置并启用 SystemdCgroup：
  • sudo mkdir -p /etc/containerd && containerd config default | sudo tee /etc/containerd/config.toml
  • 编辑 /etc/containerd/config.toml，将 [plugins.“io.containerd.grpc.v1.cri”.containerd.runtimes.runc.options] 下的 SystemdCgroup 设为 true
  • sudo systemctl enable --now containerd
• 安装 kubeadm/kubelet/kubectl 并锁定版本：sudo apt install -y kubelet kubeadm kubectl && sudo apt-mark hold kubelet kubeadm kubectl

2. 正确配置容器运行时（两种路径，二选一）

• 路径A containerd（推荐）：无需额外组件，使用上一步的 containerd 即可。
• 路径B 继续使用 Docker（需 cri-dockerd）：
  • 安装 cri-dockerd（参考其官方发布包），启用服务：sudo systemctl enable --now cri-docker.socket cri-docker
  • 初始化时指定 cri-dockerd 端点：sudo kubeadm init --cri-socket unix:///var/run/cri-dockerd.sock …

3. 系统参数与网络就绪

• 关闭 swap：sudo swapoff -a && sudo sed -i ‘/ swap / s/^/#/’ /etc/fstab
• 加载内核模块并设置 sysctl：
  • sudo modprobe br_netfilter
  • echo -e “net.bridge.bridge-nf-call-iptables=1\nnet.bridge.bridge-nf-call-ip6tables=1\nvm.swappiness=0” | sudo tee /etc/sysctl.d/k8s.conf && sudo sysctl --system
• 统一 iptables 后端（避免 nftables 与 iptables 混用导致规则不生效）：sudo update-alternatives --config iptables，选择 iptables-legacy
• 放通端口（按实际防火墙放行）：6443（API）、2379/2380（etcd）、10250（kubelet）、10251/10252（kube-scheduler/kube-controller-manager）、以及 30000-32767（NodePort）

4. 初始化与网络插件

• 初始化（containerd 示例）：sudo kubeadm init --pod-network-cidr=10.244.0.0/16；如使用 cri-dockerd，加上 –cri-socket unix:///var/run/cri-dockerd.sock
• 配置 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/tigera-operator.yaml && kubectl apply -f https://docs.projectcalico.org/manifests/custom-resources.yaml
• 验证：kubectl get nodes 应为 Ready

三 典型场景与命令示例

• 场景A 已安装 Docker 导致 kubelet 启动失败
  • 处理：sudo apt remove --purge docker.io；安装并启用 containerd；按“路径A”初始化。
• 场景B 必须保留 Docker（业务约束）
  • 处理：安装 cri-dockerd；初始化时加 –cri-socket unix:///var/run/cri-dockerd.sock；后续组件通过 cri-dockerd 对接 Docker。
• 场景C 节点 NotReady、Pod 网络不通
  • 处理：确认 swap off、iptables-legacy、bridge-nf-call-iptables=1 已生效；检查 6443/2379/2380 等端口连通；查看 journalctl -u kubelet -xe 与 kubectl describe pod -n kube-system 定位。

四 版本兼容与长期稳定建议

• 运行时选择：优先 containerd；若必须用 Docker，确保安装并启用 cri-dockerd，且 Kubernetes 版本与 Docker/cri-dockerd 版本匹配。
• 版本对齐：部署前对照 Kubernetes 与 Docker/containerd 的兼容矩阵，避免不兼容组合引发启动或调度异常。
• 版本锁定：生产环境使用 apt-mark hold kubelet kubeadm kubectl 防止意外升级导致集群波动。
• 升级策略：遵循“先测试、后滚动升级”的流程，先 kubeadm upgrade plan 评估，再 kubeadm upgrade apply 。