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 初始化与加入等流程,便于复用与标准化。