在 Debian 上使用 kubeadm 安装 Kubernetes 的完整步骤

一 环境准备与前置检查

• 节点规划：至少准备 1 台控制平面（Master） 与 1 台及以上工作节点（Worker）；建议各节点配置 ≥2 核 CPU、≥2GB 内存、≥20GB 磁盘，并确保节点间 网络互通（同一局域网或可达）。
• 系统版本：建议使用 Debian 11/12，并提前完成系统更新：
  sudo apt update & & sudo apt upgrade -y
• 主机标识：为各节点设置唯一 主机名，必要时在 /etc/hosts 中做解析，避免冲突。
• 虚拟化/克隆环境：确保各节点的 MAC 地址 与 product_uuid 唯一，避免 kubelet 误判为同一节点。
• 容器运行时：Kubernetes 需要容器运行时，常见选择为 Docker/containerd；本文以 Docker 为例（containerd 亦可）。

二 安装容器运行时与系统参数

• 安装 Docker（示例为 Debian 官方仓库方式）：
  sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
  curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg
  echo “deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  sudo apt update & & sudo apt install -y docker-ce docker-ce-cli containerd.io
  sudo systemctl enable --now docker
• 关闭 Swap（Kubernetes 要求）：
  sudo swapoff -a
  sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
• 加载内核模块与开启桥接转发（容器网络所需）：
  sudo modprobe overlay
  sudo modprobe br_netfilter
  echo -e “overlay\nbr_netfilter” | sudo tee /etc/modules-load.d/k8s.conf
  cat < < EOF | sudo tee /etc/sysctl.d/99-kubernetes.conf
  net.bridge.bridge-nf-call-iptables = 1
  net.ipv4.ip_forward = 1
  net.bridge.bridge-nf-call-ip6tables = 1
  EOF
  sudo sysctl --system

三 安装 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 > /dev/null
  sudo apt update

  如需固定版本（示例：v1.26.0）

  sudo apt install -y kubelet=1.26.0-00 kubeadm=1.26.0-00 kubectl=1.26.0-00

  或安装最新稳定版

  sudo apt install -y kubelet kubeadm kubectl
  sudo apt-mark hold kubelet kubeadm kubectl
• 启动 kubelet（开机自启，等待被 kubeadm 接管）：
  sudo systemctl enable --now kubelet

四 初始化控制平面与配置 kubectl

• 初始化 Master（示例命令，按需调整参数）：
  sudo kubeadm init \ –apiserver-advertise-address < MASTER_IP> \ –control-plane-endpoint < MASTER_IP> :6443 \ –pod-network-cidr 10.244.0.0/16 \ –service-cidr 10.100.0.0/16 \ –image-repository registry.aliyuncs.com/google_containers \ –kubernetes-version v1.26.0
  说明：
  • 国内环境可使用 registry.aliyuncs.com/google_containers 加速镜像拉取；
  • pod-network-cidr 需与所选网络插件一致（Flannel 常用 10.244.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
• 安装网络插件（二选一，确保与 pod-network-cidr 匹配）：

  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
• 可选：若初始化时未生成 token 或已过期，可在 Master 上创建新 token：
  kubeadm token create --print-join-command

五 加入工作节点与验证

• 在 Worker 节点执行加入命令（来自 kubeadm init 输出或 kubeadm token create --print-join-command）：
  sudo kubeadm join < MASTER_IP> :6443 \ –token \ –discovery-token-ca-cert-hash sha256:
• 在 Master 上验证：
  kubectl cluster-info
  kubectl get nodes
  kubectl get pods -n kube-system
• 简单应用测试：
  kubectl create deployment nginx-demo --image=nginx:1.25 --replicas=2
  kubectl expose deployment nginx-demo --port=80 --type=NodePort
  kubectl get svc nginx-demo

  使用任一节点 IP 与 NodePort 访问测试（例如 http://< NODE_IP> :< NODE_PORT> ）

六 常见问题与排错要点

• 镜像拉取失败：优先使用国内镜像仓库（如 registry.aliyuncs.com/google_containers），或提前在各节点手动 docker pull 所需镜像。
• 节点 NotReady：多因网络插件未就绪或 pod-network-cidr 不匹配；检查 kube-system 中 kube-flannel 或 calico Pod 状态与日志。
• kubelet 启动失败：确认 Swap 已关闭、内核参数生效、容器运行时已启动，并检查 journalctl -xeu kubelet 输出。
• 加入节点失败：确认 token 未过期、CA 证书哈希正确、6443/10250 等端口 放通、时间同步（建议启用 NTP）。
• 克隆虚拟机导致冲突：确保 MAC 地址 与 product_uuid 唯一，必要时在虚拟化平台重新生成。
• 版本不一致：控制平面与节点上的 kubelet/kubeadm/kubectl 版本尽量保持一致，避免组件通信异常。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！