Ubuntu 部署 Kubernetes 的主要难点
一 系统环境与内核前置条件
- 必须禁用 Swap，否则 kubelet 预检失败或运行异常；需要同时执行临时关闭与在 /etc/fstab 中永久注释，否则重启后问题复现。
- 需要正确开启内核网络转发与桥接相关参数（如 net.bridge.bridge-nf-call-iptables=1、net.ipv4.ip_forward=1），否则 CNI 网络无法正常工作。
- 容器运行时与 kubelet 的 cgroup 驱动需一致（常见为 systemd）；不一致会导致 kubelet 无法启动或频繁重启。
- 在 Kubernetes 1.24+ 使用 Docker 需额外安装 cri-dockerd，否则会出现 “CRI v1 runtime API is not implemented … cri-dockerd.sock” 等错误。
- 常见报错还包括控制面组件未就绪、节点无法注册等，多与上述基础条件缺失有关。
二 容器运行时与版本兼容
- 版本匹配是高频“坑点”：例如 K8s 1.22.4 + Docker 23.0.3 需要额外配置 cri-dockerd；而 K8s 1.23.x 搭配较新的 Docker 也可能出现 CRI 不匹配。
- 自 v1.24 起移除内置 Docker Shim，推荐直接使用 containerd（或 CRI-O）；若坚持用 Docker，务必确保 cri-dockerd 正确安装并启用。
- 运行时与 kubelet 的 cgroup 驱动不一致（如 Docker 用 cgroupsfs，kubelet 用 systemd）会导致 Pod 无法创建或 kubelet 异常。
三 网络连通性与 CNI 插件
- 初始化控制面后若未立即部署 CNI 插件，会看到 “Container runtime network not ready: cni config uninitialized”，节点无法注册；需按所选插件（如 Flannel、Calico）的文档在初始化后尽快部署。
- 节点间与节点到 API Server（默认 6443）的通信必须通畅；云上环境若用公网 IP直连，常因路由与安全组限制导致 “dial tcp …:6443: connect: connection refused” 或节点注册超时。
- Pod 访问外网或 DNS 解析异常，常见于节点 /etc/resolv.conf 配置不当（如 127.0.1.1 导致解析失败）、或宿主机 iptables FORWARD 策略为 DROP（Docker 可能修改默认策略），需调整 resolv.conf、启用 FORWARD 或更新网络插件版本。
- 初始化时指定的 Pod CIDR 需与所选 CNI 插件默认网段匹配（如 Flannel 常用 10.244.0.0/16），否则会出现网络不通或 Pod 无法分配地址。
四 镜像拉取与仓库访问
- 官方镜像仓库在某些网络环境下访问受限，初始化时容易卡在 “Pulling images …” 或报 “ImagePull” 错误；需提前使用 kubeadm config images pull 拉取，或配置国内镜像源/私有仓库。
- 历史案例中 pause 镜像默认地址不可达，需要在 kubelet 配置中显式指定可拉取的镜像地址。
- 使用较新版本组件时，还需考虑 CRI 接口变更导致的兼容性问题（见第二部分）。
五 存储与持久化配置
- 初次接触常遇到 PVC 一直处于 Pending，多由 NFS 服务未就绪、节点未安装 NFS 客户端、权限/路径错误 或 StorageClass/Provisioner 不匹配引起；需按步骤在节点安装 nfs-common、正确导出共享目录并在集群中创建可用的 PV/PVC/StorageClass。
- 选择存储方案要结合场景：NFS 便于多节点共享，Ceph（Rook） 更适合生产级块/对象/文件存储；HostPath 仅适合单节点测试，生产不可用。
- 生产环境还需考虑备份恢复（如 Velero）、容量规划与性能调优，避免单点故障和数据不可达。
