Kubernetes与Debian系统兼容性问题

Kubernetes与Debian的兼容性要点与落地配置

一 支持矩阵与版本选择

• 操作系统建议选用Debian 12（Bookworm）或Debian 11（Bullseye）的稳定版本，避免使用Testing/Unstable。Kubernetes对内核特性有要求，Debian 11/12默认内核通常满足需求（常见要求为≥5.10，最低不低于3.10）。从v1.24起，Kubernetes移除内置的Docker支持，推荐使用containerd作为容器运行时。组件版本建议保持一致，并用包管理锁定以避免意外升级导致不兼容。

二 常见兼容性问题与对策

• 内核与网络栈
  • 现象：Pod网络不通、Service不可达、bridge-nf-call-iptables相关报错。
  • 处理：加载模块并开启关键sysctl
    • 模块：overlay、br_netfilter
    • sysctl：net.bridge.bridge-nf-call-iptables=1、net.ipv4.ip_forward=1（按需启用IPv6项）
• Swap未关闭
  • 现象：kubelet拒绝调度或频繁报错。
  • 处理：临时执行swapoff -a，并在/etc/fstab注释swap行实现永久关闭。
• 容器运行时与Docker
  • 现象：kubeadm init失败、CRI不可用。
  • 处理：安装并启用containerd（确保CRI插件启用），Kubernetes **v1.24+**不再内置支持Docker，若必须使用Docker需通过cri-dockerd适配，生产更推荐直接使用containerd。
• iptables与nftables冲突
  • 现象：iptables规则不生效、网桥转发异常。
  • 处理：将iptables/ip6tables切换到legacy模式以避免nftables兼容问题（update-alternatives）。
• 防火墙/端口未放行
  • 现象：节点NotReady、组件无法通信。
  • 处理：放行关键端口（如6443、2379-2380、10250等），或临时关闭防火墙用于排查。
• 版本漂移与组件不一致
  • 现象：升级后kubelet/kubeadm不兼容、集群异常。
  • 处理：使用APT源安装后用apt-mark hold固定kubelet/kubeadm/kubectl版本，升级按官方路径小步迭代。

三 落地配置清单（可直接复用）

• 系统与内核
  • 升级并重启：apt update && apt upgrade -y
  • 加载模块与sysctl
    • /etc/modules-load.d/containerd.conf
      • overlay
      • br_netfilter
    • /etc/sysctl.d/99-kubernetes-k8s.conf
      • net.bridge.bridge-nf-call-iptables = 1
      • net.ipv4.ip_forward = 1
    • 执行：modprobe overlay && modprobe br_netfilter && sysctl --system
• 关闭Swap
  • swapoff -a
  • sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
• 容器运行时containerd
  • apt install -y containerd
  • systemctl enable --now containerd
  • 确认/etc/containerd/config.toml中CRI插件启用并重启服务
• 安装与锁定Kubernetes组件
  • 导入GPG并添加仓库（示例）
    • curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add -
    • echo “deb https://apt.kubernetes.io/ kubernetes-xenial main” | tee /etc/apt/sources.list.d/kubernetes.list
  • apt update && apt install -y kubelet kubeadm kubectl
  • apt-mark hold kubelet kubeadm kubectl
• 初始化与网络插件
  • kubeadm init --pod-network-cidr=10.244.0.0/16（与所选CNI匹配）
  • mkdir -p $HOME/.kube && cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && chown $(id -u):$(id -g) $HOME/.kube/config
  • 安装Flannel：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
  • 验证：kubectl get nodes 显示Ready

四 故障排查与验证

• 查看组件日志：journalctl -u kubelet -f、journalctl -u kubeadm -f
• 检查节点与系统状态：kubectl get nodes、kubectl get pods -n kube-system
• 网络连通性：在节点上验证Pod网段路由、跨节点端口可达性（如6443、10250）
• 防火墙与端口：按需放行或使用ufw disable临时排除干扰，再定位问题根源