如何在Ubuntu上搭建Kubernetes环境

在 Ubuntu 上使用 kubeadm 搭建 Kubernetes 集群

一 环境准备与前置检查

• 系统要求：建议使用 Ubuntu 20.04/22.04/24.04，每台机器至少 2GB 内存、2 个 CPU 核心、20GB+ 磁盘，并确保节点间 IP 互通、主机名唯一。
• 基础配置：
  • 关闭交换分区：sudo swapoff -a 并注释 /etc/fstab 中的 swap 行，避免 kubelet 异常。
  • 设置主机名与 hosts：
    • sudo hostnamectl set-hostname master（主节点），worker1/worker2（工作节点）
    • 编辑 /etc/hosts：
      • 192.168.1.100 master
      • 192.168.1.101 worker1
      • 192.168.1.102 worker2
  • 防火墙与内核模块：放行 6443/10250/10251/10252 等端口或临时关闭防火墙；按需加载 br_netfilter、overlay 模块并开启转发：
    • sudo modprobe br_netfilter
    • echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-iptables
    • echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward
• 容器运行时：安装并启动 Docker，并配置 cgroup driver=systemd（与 kubelet 一致）：
  • sudo apt-get update && sudo apt-get install -y docker.io
  • 配置 /etc/docker/daemon.json：
    • { "exec-opts": ["native.cgroupdriver=systemd"], "log-driver": "json-file", "log-opts": { "max-size": "100m" }, "storage-driver": "overlay2" }
  • sudo systemctl enable --now docker
    以上准备可显著提升初始化成功率与后续稳定性。

二 安装 kubeadm kubelet kubectl

• 添加 Kubernetes APT 源并安装组件（版本可按需锁定，如 1.30.x）：
  • sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates curl
  • curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor | sudo tee /usr/share/keyrings/kubernetes-archive-keyring.gpg >/dev/null
  • 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-get update && sudo apt-get install -y kubelet kubeadm kubectl
  • sudo apt-mark hold kubelet kubeadm kubectl（防止被系统升级干扰）
• 启动 kubelet：
  • sudo systemctl enable --now kubelet
    上述步骤为官方推荐做法，适用于 Ubuntu 20.04/22.04/24.04。

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

• 在主节点初始化（Pod 网段可按网络插件要求调整，常见为 192.168.0.0/16 或 10.244.0.0/16）：
  • sudo kubeadm init --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
• 安装网络插件（二选一，保持与上面 Pod CIDR 一致）：
  • Calico：kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
  • Flannel：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
• 检查节点状态：kubectl get nodes（首次可能需要等待网络插件就绪）
  以上流程为 kubeadm 的标准初始化与网络接入方式。

四 加入工作节点与验证

• 在工作节点执行主节点初始化输出中的 kubeadm join 命令（包含 token 与 discovery-token-ca-cert-hash），示例：
  • sudo kubeadm join 192.168.1.100:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>
• 如 token 过期，可在主节点重新生成：
  • sudo kubeadm token create --print-join-command
• 在主节点验证：kubectl get nodes，所有节点状态应为 Ready。
• 简单功能验证：
  • kubectl create deployment nginx --image=nginx
  • kubectl expose deployment nginx --port=80 --type=NodePort
  • kubectl get svc nginx（获取 NodePort 后在浏览器访问 http://<任意节点IP>:<NodePort>）
    以上为加入节点与基础连通性验证的通用步骤。

五 常见问题与排查要点

• 节点 NotReady：优先检查网络插件是否成功部署、Pod CIDR 是否与初始化参数一致、以及节点间 6443/10250 等端口连通性。
• kubelet 启动失败：确认已关闭 swap、cgroup driver 为 systemd、以及 /var/lib/kubelet 目录权限正确。
• 镜像拉取慢或失败：可配置国内镜像源或使用 imagePullPolicy: IfNotPresent；必要时提前 docker pull 所需镜像。
• 加入节点失败：确认 token 未过期、时间同步（建议 NTP）、以及控制平面 6443 端口对节点开放。
• 重置与清理：如需重建，可在节点执行 sudo kubeadm reset -f，并清理 /etc/cni/net.d、/var/lib/kubelet 等残留目录后再试。