Debian服务器Kubernetes安装教程

在 Debian 12 上使用 kubeadm 安装 Kubernetes 集群

一 环境准备与前置检查

• 节点规划：至少 1 台 Master + 1 台 Worker；推荐 Debian 12，满足 2 核 CPU / 2GB 内存 / 20GB 磁盘 以上；各节点间网络互通，主机名唯一，时间同步（建议启用 NTP/chrony）。
• 禁用 Swap：执行 sudo swapoff -a，并在 /etc/fstab 中注释 swap 行，避免 kubelet 启动失败。
• 容器运行时：Kubernetes 支持 containerd 或 Docker（通过 cri-dockerd 适配）；本文提供 containerd 方案（更贴近当前主流实践）。
• 防火墙与安全组：确保节点放行必要端口（见文末端口表）。

二 所有节点安装与配置

• 更新系统与基础工具

  sudo apt update && sudo apt upgrade -y
  sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
  

• 安装并配置 containerd（推荐）
  1. 安装

     sudo apt install -y containerd
     sudo systemctl enable --now containerd
     

  2. 生成默认配置并启用 CRI

     sudo mkdir -p /etc/containerd
     containerd config default | sudo tee /etc/containerd/config.toml
     # 若使用 systemd cgroup，确保配置中 SystemdCgroup = true
     sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml
     sudo systemctl restart containerd
     

• 安装 kubeadm、kubelet、kubectl

  # 导入 Kubernetes GPG 公钥（Debian 12 常见为 bookworm）
  curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/kubernetes-apt-keyring.gpg
  echo "deb [signed-by=/usr/share/keyrings/kubernetes-apt-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | \
    sudo tee /etc/apt/sources.list.d/kubernetes.list > /dev/null
  
  sudo apt update
  sudo apt install -y kubelet kubeadm kubectl
  sudo apt-mark hold kubelet kubeadm kubectl
  sudo systemctl enable --now kubelet
  

• 内核与网络参数（桥接与转发）

  sudo modprobe overlay
  sudo modprobe br_netfilter
  
  cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
  overlay
  br_netfilter
  EOF
  
  cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes.conf
  net.bridge.bridge-nf-call-iptables  = 1
  net.bridge.bridge-nf-call-ip6tables = 1
  net.ipv4.ip_forward                 = 1
  EOF
  
  sudo sysctl --system
  

• 可选 使用 Docker 作为运行时（通过 cri-dockerd）
  1. 安装 Docker（略，参考 Docker 官方 APT 源）。
  2. 安装 cri-dockerd（参考其 GitHub 发布页），并配置 kubelet 使用 --container-runtime=remote --container-runtime-endpoint=unix:///run/cri-dockerd.sock。

三 初始化控制平面 Master

• 初始化命令（按需替换参数）

  # 单 Master 常用示例（Pod 网段与 Flannel 默认匹配）
  sudo kubeadm init \
    --apiserver-advertise-address=<MASTER_IP> \
    --pod-network-cidr=10.244.0.0/16 \
    --service-cidr=10.96.0.0/12 \
    --image-repository=registry.k8s.io
  

  国内环境可替换镜像仓库为 registry.aliyuncs.com/google_containers 以加速拉取。初始化成功后，控制台会输出 kubeadm join ... 命令，请妥善保存。
• 配置 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（与 10.244.0.0/16 匹配）

    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
    kubectl apply -f https://docs.projectcalico.org/manifests/custom-resources.yaml
    

• 验证

  kubectl cluster-info
  kubectl get nodes
  kubectl get pods -A
  

四 加入 Worker 节点

• 在 Worker 节点执行 Master 初始化输出的命令（示例）

  sudo kubeadm join <MASTER_IP>:6443 \
    --token <TOKEN> \
    --discovery-token-ca-cert-hash sha256:<HASH>
  

• 如 token 过期，可在 Master 上生成新的加入命令

  kubeadm token create --print-join-command
  

• 回到 Master 验证

  kubectl get nodes
  

五 常见问题与运维命令

• 常用运维
  • 重置节点（重装前清理）

    sudo kubeadm reset -f
    sudo rm -rf /etc/cni/net.d
    sudo iptables -F && sudo iptables -t nat -F && sudo iptables -t mangle -F && sudo iptables -X
    

  • 检查与排查

    kubectl get nodes -o wide
    kubectl get pods -A -o wide
    journalctl -u kubelet -xe
    

• 端口放行参考
  • Master：6443（API）、2379-2380（etcd）、10250（kubelet）、10251（kube-scheduler）、10252（kube-controller-manager）
  • Worker：10250（kubelet）、30000-32767（NodePort 范围）
    如使用 UFW：sudo ufw allow <端口>/tcp 并 sudo ufw reload。