如何在Debian上成功安装Kubernetes

在 Debian 上安装 Kubernetes 的实操指南

一 环境准备与前置条件

• 操作系统建议使用 Debian 10+，硬件至少 2 核 CPU、2GB 内存、20GB 磁盘，并确保各节点间 网络互通、时间同步、主机名唯一。
• 在所有节点执行：
  • 更新系统：sudo apt update && sudo apt upgrade -y
  • 安装基础工具：sudo apt install -y apt-transport-https ca-certificates curl
  • 关闭 Swap：sudo swapoff -a 并注释 /etc/fstab 中的 swap 行，避免 kubelet 启动失败。
  • 可选但推荐：启用桥接流量转发（后续 sysctl 会用到）。

二 安装容器运行时

• 推荐运行时为 containerd（Kubernetes 自 v1.24 起内置 cri-dockerd 以兼容 Docker，但生产更建议直接使用 containerd）。
• 安装 containerd（Debian 官方仓库通常已提供）：
  • sudo apt install -y containerd
  • 生成默认配置并启用 SystemdCgroup：
    • sudo mkdir -p /etc/containerd
    • containerd config default | sudo tee /etc/containerd/config.toml
    • 编辑 /etc/containerd/config.toml，将 [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options] 下的 SystemdCgroup 设为 true
  • 启动并自启：sudo systemctl enable --now containerd
• 如必须使用 Docker（仅作兼容过渡）：
  • sudo apt install -y docker.io
  • sudo systemctl enable --now docker
  • 注意自 v1.24 起需额外配置 cri-dockerd 才能让 kubelet 通过 CRI 调用 Docker。

三 安装 kubeadm kubelet kubectl

• 添加 Kubernetes APT 源并安装组件：
  • curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/kubernetes-archive-keyring.gpg
  • echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
  • sudo apt update && sudo apt install -y kubelet kubeadm kubectl
  • 锁定版本避免误升级：sudo apt-mark hold kubelet kubeadm kubectl
• 启动 kubelet（先不启动集群，等初始化时再拉起）：sudo systemctl enable --now kubelet

四 初始化控制平面并安装网络插件

• 在 Master 节点初始化（将 替换为你的主节点 IP）：
  • 使用 Flannel 时推荐：sudo kubeadm init --apiserver-advertise-address=<master-ip> --pod-network-cidr=10.244.0.0/16
  • 使用 Calico 时推荐：sudo kubeadm init --apiserver-advertise-address=<master-ip> --pod-network-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
• 安装 CNI 网络插件（二选一）：
  • 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
• 等待节点 Ready：kubectl get nodes

五 加入工作节点与验证

• 在 Worker 节点执行 kubeadm init 完成后输出的 kubeadm join 命令（包含 token 与 discovery-token-ca-cert-hash），例如：
  • sudo kubeadm join <master-ip>:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>
• 如 token 过期，在 Master 生成新命令：kubeadm token create --print-join-command
• 验证：kubectl get nodes 应显示所有节点 Ready。

六 常见问题与排障要点

• 端口与防火墙：确保放行 6443、2379-2380、10250、10251、10252（Master） 与 10250、30000-32767（Worker）；云环境需配置安全组。
• Swap 未关闭：kubelet 会拒绝启动，务必执行 swapoff -a 并注释 /etc/fstab。
• 内核与网络栈：
  • 启用桥接转发：sudo sysctl -w net.bridge.bridge-nf-call-iptables=1 与 net.ipv4.ip_forward=1（写入 /etc/sysctl.d/99-k8s.conf 持久化）
  • 若遇到 iptables/nftables 兼容性问题，可切换为 iptables-legacy：sudo update-alternatives --config iptables
• 镜像拉取慢或失败（国内环境）：
  • 使用国内镜像仓库（如 registry.aliyuncs.com/google_containers）初始化：sudo kubeadm init --image-repository=registry.aliyuncs.com/google_containers ...
  • 或配置 containerd 镜像加速（registry mirrors）。
• 重置与重装：
  • sudo kubeadm reset
  • 清理 CNI 与防火墙规则：sudo rm -rf /etc/cni/net.d && sudo iptables -F && sudo iptables -t nat -F && sudo iptables -t mangle -F && sudo iptables -X