Debian 上安装 Kubernetes 的关键注意事项
一 系统与资源准备
- 选择稳定的操作系统版本，优先使用 Debian 12（Bookworm） 或更高版本，内核与驱动支持更好。
- 资源基线建议：每节点至少 2 核 CPU、2GB 内存、20GB 磁盘，并确保节点间网络稳定、互通。
- 主机名与解析：为每个节点设置唯一 hostname，如无内网 DNS，需在 /etc/hosts 中配置节点 IP–主机名 映射，避免组件通信异常。
- 基础环境：系统更新到最新补丁；确保 systemd 正常运行；如使用云盘或虚拟化，确认驱动与挂载选项稳定。
二 内核与系统参数
- 禁用 Swap：Kubernetes 要求关闭 Swap。执行
sudo swapoff -a 临时关闭，并在 /etc/fstab 中注释含 “swap” 的行以永久生效。
- 开启桥接与转发：确保加载 overlay/br_netfilter 模块，并开启桥接流量进入 iptables 与 IPv4 转发。示例：
- 模块：
sudo modprobe overlay && sudo modprobe br_netfilter
- Sysctl：
net.bridge.bridge-nf-call-iptables = 1、net.bridge.bridge-nf-call-ip6tables = 1、net.ipv4.ip_forward = 1
- 持久化：
sudo sysctl --system 使配置生效。
三 容器运行时与组件安装
- 运行时选择：自 v1.24 起，Kubernetes 移除内置 dockershim，推荐使用 containerd（或 CRI-O）。如使用 Docker，需通过 cri-dockerd 适配。
- 安装 containerd（示例）：
sudo apt install -y containerd && sudo systemctl enable --now containerd，并按需生成默认配置与镜像仓库加速。
- 安装 kubeadm/kubelet/kubectl：添加 Kubernetes APT 源，安装后将 kubelet/kubeadm/kubectl 标记为 hold，避免被系统升级干扰：
sudo apt-mark hold kubelet kubeadm kubectl。
- 版本策略：避免跨多版本跳跃升级，先小版本验证再滚动升级，确保组件版本匹配与控制平面/节点组件兼容。
四 网络与安全配置
- 防火墙放行：若启用 UFW，需放行关键端口（示例）
- 控制平面：6443/TCP（API）、2379–2380/TCP（etcd）、10250/TCP（kubelet）、10251/TCP（kube-scheduler）、10252/TCP（kube-controller-manager）、10255/TCP（kubelet 只读）
- 工作节点：10250/TCP、30000–32767/TCP（NodePort 范围）
- 网络插件：集群必须安装 CNI 插件后才能调度 Pod。常见选择：
- 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
- 节点互通：确认节点间 IP 互通、时间同步（NTP/chrony）、以及云厂商 安全组/ACL 已放通上述端口与 Pod CIDR。
五 初始化与验证及常见坑
- 初始化控制平面：
- 指定 Pod CIDR（与所选网络插件匹配），如 Flannel 常用 10.244.0.0/16：
sudo kubeadm init --pod-network-cidr=10.244.0.0/16
- 如使用 Calico，按其文档设置 Pod CIDR（常见 192.168.0.0/16），避免与宿主机网段冲突。
- 配置 kubectl：
mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config
- 加入工作节点：使用
kubeadm join ... 命令（由 init 输出），确保 token 未过期、CA 哈希一致。
- 验证：
kubectl cluster-info、kubectl get nodes（状态应为 Ready）。
- 常见问题速查：
- 镜像拉取失败：配置 镜像仓库镜像/代理，或提前
kubeadm config images pull
- Pod 启动失败/环境变量过多：在 Pod spec 中设置 enableServiceLinks: false
- 节点 NotReady：检查 CNI 是否安装、Pod CIDR 是否匹配、kubelet 是否 Running、防火墙/安全组是否放通。