Debian 部署 Kubernetes 的主要难点
在 Debian 上搭建 Kubernetes 的门槛主要集中在系统底层配置、容器运行时与网络三大方面，既要满足 K8s 的强制前置条件，又要处理好与容器运行时的兼容与网络插件落地。
一 系统与内核前置条件的坑
- 必须禁用 Swap，否则 kubelet 无法正常工作；需要同时执行临时关闭与修改 /etc/fstab 永久生效。该步骤遗漏或恢复开启，常见现象是节点 NotReady 或 kubelet 反复重启。
- 需要加载并持久化内核模块与网络参数：加载 overlay、br_netfilter，并设置 net.bridge.bridge-nf-call-iptables=1、net.bridge.bridge-nf-call-ip6tables=1、net.ipv4.ip_forward=1，否则会出现同节点 Pod 之间或跨节点通信异常。
- 防火墙与安全模块常导致端口或系统调用被拦截：需按需放行 6443、2379、2380、10250、10251、10252、10255 等关键端口；Debian 常见的是 nftables/iptables 与 UFW，而部分教程还建议关闭 AppArmor（生产环境不建议直接关闭，应改为精细化策略）。
- 主机名与 DNS/hosts 解析要稳定，避免因解析异常导致组件注册与调度异常。
二 容器运行时与 kubelet 的兼容与配置
- 运行时选择：自 v1.20 起，Kubernetes 不再直接支持 Docker 作为容器运行时，推荐使用 containerd 或 CRI-O；若坚持使用 Docker，需额外部署 cri-dockerd 适配 CRI。
- cgroup 驱动不一致是高频“坑点”：例如 containerd 默认 cgroup v1 而 kubelet 使用 systemd cgroup v2（或反之），会导致 kubeadm init 后 6443 被拒绝、控制面组件反复 CrashLoopBackOff。需在 /etc/containerd/config.toml 中启用 SystemdCgroup = true 并重启服务。
- 镜像拉取与版本匹配：初始化依赖的 kube-apiserver、kube-controller-manager、kube-scheduler、etcd、coredns、pause 等镜像若无法从 k8s.gcr.io 拉取，需配置可用镜像源或提前导入；同时 kubelet/kubeadm/kubectl 版本需匹配且遵循兼容性规则（通常允许与控制面相差一个次版本，但 kubelet 不可高于 API Server）。
三 网络方案与端口放行的落地
- 必须部署 CNI 网络插件（如 Calico、Flannel），否则 Pod 之间无法互通；不同插件对 Pod CIDR 有要求，例如 Flannel 常用 10.244.0.0/16，需与 kubeadm 初始化参数一致。
- 节点间与组件间通信依赖多端口：控制面 6443，etcd 2379/2380，kubelet 10250，调度器 10251，控制器管理器 10252，以及 NodePort 范围等；若使用 UFW，需显式放行对应端口，避免“能部署但访问不通”。
- 跨主机网络还受底层网络影响（如云厂商 VPC/安全组、物理交换机的 MTU/ACL），常见问题表现为 Pod 间跨节点不通或 Service 访问超时。
四 镜像、资源与日常运维的易错点
- 国内环境常遇到 gcr.io 镜像拉取失败，需通过镜像仓库加速或提前导入；初始化失败或组件 Crash 时，优先检查镜像是否就位。
- 资源不足（CPU/内存）会导致节点 NotReady、Pod 被驱逐；需合理设置 requests/limits 或扩容节点。
- 证书与 RBAC 配置不当会出现 TLS 错误或权限不足；kubeconfig 路径与上下文错误也会导致 kubectl 无法连接。
- 日志与排障路径要清晰：用 journalctl -u kubelet、kubectl logs、kubectl describe pod 快速定位；必要时检查 /var/log/syslog、dmesg 与网络连通性。
