Debian上安装 Kubernetes 的实用技巧
一 环境与前置检查
- 选择稳定的系统版本：优先使用 Debian 12（Bookworm），资源建议至少 2 核 CPU、2–4GB 内存、20GB 磁盘，并确保节点间网络互通与 静态 IP。
- 主机名与解析：为每个节点设置唯一 hostname，并在 /etc/hosts 中添加解析，便于内网直连与排查。
- 时间同步：启用 NTP/chrony，避免证书校验与组件通信异常。
- 唯一性校验：确保各节点的 MAC 地址 与 product_uuid 唯一，避免克隆环境导致冲突。
- 基础依赖：提前安装 apt-transport-https、ca-certificates、curl、software-properties-common 等工具，减少后续报错。
二 容器运行时与内核参数
- 运行时选择：生产环境推荐 containerd（与 kubelet 集成更紧密）；若使用 Docker，需确保其内置的 containerd 正常工作。
- containerd 关键配置：启用 SystemdCgroup = true，并重启服务生效。
- 内核模块与 sysctl：加载 overlay、br_netfilter，开启桥接流量进入 iptables 与 ip_forward，保证 Pod 网络与跨节点通信。
- 快速示例（containerd）：
- 配置模块：
- echo -e “overlay\nbr_netfilter” | sudo tee /etc/modules-load.d/containerd.conf && sudo modprobe overlay && sudo modprobe br_netfilter
- 配置 sysctl：
- echo -e “net.bridge.bridge-nf-call-iptables = 1\nnet.ipv4.ip_forward = 1” | sudo tee /etc/sysctl.d/99-kubernetes-k8s.conf && sudo sysctl --system
- containerd 配置片段：
- [plugins.“io.containerd.grpc.v1.cri”.containerd.runtimes.runc.options] SystemdCgroup = true
- sudo systemctl restart containerd && sudo systemctl enable containerd
三 kubeadm 初始化与网络插件
- 安装组件：添加 Kubernetes APT 源，安装 kubelet、kubeadm、kubectl，并使用 apt-mark hold 固定版本，避免被系统升级干扰。
- 初始化命令：在主节点执行 kubeadm init，常见组合为 –pod-network-cidr=10.244.0.0/16（Flannel）或 –pod-network-cidr=192.168.0.0/16（Calico）；可按需设置 –service-cidr=10.96.0.0/12。
- kubectl 配置：将 /etc/kubernetes/admin.conf 拷贝至 $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/tigera-operator.yaml 与 custom-resources.yaml
- 加入节点：妥善保存 kubeadm init 输出的 kubeadm join 命令，在 Worker 节点执行以加入集群。
四 防火墙与端口规划
- UFW 场景（示例）：
- 放行 6443/tcp（API Server）、2379–2380/tcp（etcd）、10250/tcp（kubelet）、10251/tcp（kube-scheduler）、10252/tcp（kube-controller-manager）、10255/tcp（kubelet 只读），放行后执行 ufw reload。
- firewalld/云安全组：同样需确保上述端口与节点间通信网段放通，避免因策略阻断导致组件异常。
五 常见问题与自动化部署
- 常见问题速解：
- 节点 NotReady：检查 CNI 插件是否安装、Pod CIDR 是否与网络插件一致、kubelet 是否 Running。
- 镜像拉取慢/失败：使用 国内镜像源 或配置 image-repository（如 registry.aliyuncs.com/google_containers）。
- 组件 CrashLoopBackOff：查看 kubelet 与容器运行时日志（journalctl -u kubelet -f），核对 cgroup 驱动 与 内核参数。
- Token 过期：在 Master 节点执行 kubeadm token create --print-join-command 重新生成加入命令。
- 自动化部署：
- KubeKey：一键拉起集群，支持指定 Kubernetes 版本 与 容器运行时。
- Ansible：编写 Playbook 批量执行系统准备、容器运行时、kubeadm 初始化与加入等流程，便于复用与标准化。