Kubernetes 与 Debian 的安装兼容性与实践指南
一 兼容性与版本选择
- 操作系统建议优先选用 Debian 12（Bookworm），对主流 Kubernetes 版本 的兼容性与社区实践更完善；Debian 11（Bullseye） 仍可部署，但部分新版本 K8s 的组件依赖与内核要求更高，排障成本更大。
- 自 v1.24 起，Kubernetes 移除内置的 dockershim，默认使用 containerd/CRI-O；若坚持使用 Docker，需通过 cri-dockerd 适配，但生产更推荐直接使用 containerd。
- 内核建议：Kubernetes v1.32+ 建议 Linux 内核 ≥ 4.19；Debian 12 默认内核通常满足要求，Debian 11 需确认并酌情升级内核或降低 K8s 版本。
- 版本匹配：部署前务必查阅目标 K8s 版本的官方文档与发行说明，确保 kubelet/kubeadm/kubectl 三者版本一致，并与容器运行时匹配。
二 常见兼容性问题与对策
- 容器运行时与驱动：K8s 不再内置支持 Docker，直接安装 Docker 而不做 CRI 适配会导致 kubelet 无法调度；推荐安装 containerd 并启用 systemd cgroup 驱动。如使用 Docker，需额外部署 cri-dockerd。
- iptables/nftables 兼容：部分网络插件在 nftables 环境下出现连通性问题，可通过 alternatives 切换为 iptables-legacy 以提升兼容性。
- 内核与模块：未加载 br_netfilter、未开启桥接流量转发会导致 Pod 网络异常；需确保相关内核模块与 sysctl 正确配置。
- Swap 未关闭：K8s 要求关闭 Swap，否则 kubelet 无法正常运行或节点被标记为不健康。
- 防火墙/安全组：节点间与对外访问端口未放行（如 6443、10250、2379、2380 等）会造成组件通信失败或节点 NotReady。
- 版本不匹配：kubelet/kubeadm/kubectl 或与容器运行时版本不一致，常见报错为 “image pull/CRI not found/not healthy”。
三 在 Debian 上的最小可行安装步骤
- 准备环境（所有节点）
- 关闭 Swap：sudo swapoff -a 并注释 /etc/fstab 中的 swap 行。
- 加载内核模块与 sysctl：modprobe br_netfilter；创建 /etc/sysctl.d/k8s.conf，设置 net.bridge.bridge-nf-call-iptables=1、net.bridge.bridge-nf-call-ip6tables=1、net.ipv4.ip_forward=1；执行 sysctl --system。
- 放行端口或临时关闭防火墙（测试环境）：确保 6443、10250、2379、2380 等端口互通。
- 安装容器运行时（推荐 containerd）
- 安装：sudo apt-get update && sudo apt-get install -y containerd
- 生成默认配置并启用 systemd cgroup：
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml
在 [plugins.“io.containerd.grpc.v1.cri”.containerd.runtimes.runc.options] 下确保 SystemdCgroup = true
sudo systemctl enable --now containerd
- 安装 kubeadm/kubelet/kubectl（指定一致版本并锁定）
- 导入 GPG（Debian 12 推荐 keyring 方式）：
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/kubernetes-archive-keyring.gpg
- 添加源：echo “deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main” | sudo tee /etc/apt/sources.list.d/kubernetes.list
- 安装并锁定版本（示例）：sudo apt-get update && sudo apt-get install -y kubelet=1.29.x-00 kubeadm=1.29.x-00 kubectl=1.29.x-00 && sudo apt-mark hold kubelet kubeadm kubectl
- 初始化控制平面（仅在 Master）
- kubeadm init --pod-network-cidr=10.244.0.0/16（如使用 Flannel；如使用 Calico 请按其文档设置 CIDR）
- 配置 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
- 加入工作节点
- 使用 kubeadm init 输出的 kubeadm join 命令在各 Worker 上执行。
四 验证与故障排查
- 基本验证
- kubectl cluster-info、kubectl get nodes（状态应为 Ready）、kubectl get pods -A（核心组件 Running）。
- 组件日志
- journalctl -u kubelet -f、journalctl -u containerd -f；kubeadm init/join 失败时查看输出与日志定位阶段问题。
- 网络连通性
- 确认节点间 6443/10250/2379/2380 等端口开放；Pod 间跨节点通信异常时，优先核查网络插件与节点路由/iptables。
- 资源与系统
- 资源不足会导致 Pod 调度失败或节点 NotReady；检查 CPU/内存/磁盘，并合理配置资源请求与上限。
- DNS 与 CoreDNS
- 集群就绪后若服务发现异常，检查 CoreDNS 是否 Running、是否存在循环或解析失败。
五 推荐配置与注意事项
- 操作系统与内核：优先 Debian 12 + 内核 ≥ 4.19；如使用 Debian 11，建议升级内核或选择与之匹配的 K8s 版本。
- 容器运行时：生产推荐 containerd（原生 CRI、性能与稳定性更好）；如使用 Docker，需额外部署 cri-dockerd 并正确配置 cgroup 驱动。
- 版本策略：固定 kubelet/kubeadm/kubectl 的版本并锁定，避免 apt 升级导致不一致；升级集群遵循官方升级流程。
- 网络插件：常见选择 Calico（网络策略丰富）或 Flannel（部署简单）；CIDR 需与插件及现有网络规划不冲突。
- 安全与合规：开启 RBAC、最小权限与镜像签名校验；对外暴露 API Server 建议配合 TLS 与负载均衡/认证网关。
