使用 kubeadm 部署 Kubernetes 集群指南

本文档提供一份使用 kubeadm 工具部署 Kubernetes 集群的详细步骤，旨在为部署过程提供清晰的指引。

一、 环境初始化

在部署前，需完成所有节点的基础环境配置，包括但不限于：时间同步、内核转发、主机名设置、关闭 Swap 等。

二、 安装容器运行时 (Containerd)

Kubernetes 依赖容器运行时来管理容器的生命周期。

1. 安装 containerd

   参考官方文档：containerd Getting Started

   wget https://github.com/containerd/containerd/releases/download/v2.2.1/containerd-2.2.1-linux-amd64.tar.gz
   tar -xf containerd-2.2.1-linux-amd64.tar.gz -C /usr/local/
   

   配置 systemd 服务并启动。

   wget https://raw.githubusercontent.com/containerd/containerd/main/containerd.service -O /etc/systemd/system/containerd.service
   
   systemctl daemon-reload
   systemctl enable --now containerd
   

2. 安装 runc

   wget https://github.com/opencontainers/runc/releases/download/v1.4.0/runc.amd64
   install -m 755 runc.amd64 /usr/local/sbin/runc
   

3. 安装 CNI 插件

   CNI (Container Network Interface) 插件为 Pod 提供网络能力。

   wget https://github.com/containernetworking/plugins/releases/download/v1.9.0/cni-plugins-linux-amd64-v1.9.0.tgz
   mkdir -p /opt/cni/bin
   tar -xf cni-plugins-linux-amd64-v1.9.0.tgz -C /opt/cni/bin/
   

4. 配置 cgroup 驱动

   为确保 containerd 和 kubelet 使用一致的 cgroup 驱动（systemd），需要修改 containerd 的配置。

   mkdir -p /etc/containerd
   containerd config default > /etc/containerd/config.toml
   
   # 将 SystemdCgroup 的值从 false 修改为 true
   sed -i '/SystemdCgroup/s/false/true/g' /etc/containerd/config.toml
   
   systemctl restart containerd.service
   

三、 安装 Kubernetes 组件

安装 kubeadm、kubelet 和 kubectl。

参考官方文档：安装 kubeadm

1. 配置 Kubernetes APT 仓库

   curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.35/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
   
   echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.35/deb/ /' | tee /etc/apt/sources.list.d/kubernetes.list
   

2. 安装并锁定版本

   apt-get update
   apt-get install -y kubelet kubeadm kubectl
   apt-mark hold kubelet kubeadm kubectl
   

3. 配置 kubectl 命令补全 (推荐)

   mkdir -p /etc/bash_completion.d/
   kubectl completion bash | tee /etc/bash_completion.d/kubectl > /dev/null
   chmod a+r /etc/bash_completion.d/kubectl
   

4. 配置 Kubelet

   # 在 /etc/default/kubelet 文件中指定 cgroup 驱动
   echo 'KUBELET_EXTRA_ARGS="--cgroup-driver=systemd"' > /etc/default/kubelet
   
   systemctl enable --now kubelet
   

四、 部署 Kubernetes 集群

1. 生成 kubeadm 配置文件

   kubeadm config print init-defaults > kubeadm-config.yml
   

2. 修改配置文件

   编辑 kubeadm-config.yml 文件：

   • advertiseAddress: 填写控制平面节点的IP；若为高可用集群，则填写虚拟IP (VIP)。
   • imageRepository: 国内环境建议更换为境内镜像源，如 registry.cn-hangzhou.aliyuncs.com/google_containers。
   • podSubnet: Pod 网络地址段，需与后续网络插件的配置保持一致。

3. 拉取镜像并初始化集群

   # 根据配置文件拉取镜像
   kubeadm config images pull --config=kubeadm-config.yml
   
   # 执行集群初始化
   kubeadm init --config kubeadm-config.yml --upload-certs
   

4. 配置 kubectl 凭证

   初始化成功后，根据输出提示配置 kubectl 客户端。

   # 为普通用户配置
   mkdir -p $HOME/.kube
   sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
   sudo chown $(id -u):$(id -g) $HOME/.kube/config
   
   # 或为 root 用户配置
   export KUBECONFIG=/etc/kubernetes/admin.conf
   

5. 加入节点

   在其他节点上执行 kubeadm init 成功后输出的 kubeadm join 命令，以加入集群。

   • 加入工作节点：直接使用生成的 join 命令。
   • 加入控制平面节点：使用带有 --control-plane 和 --certificate-key 参数的 join 命令。

   提示：如果加入集群的 token 或证书密钥已过期，可在主节点上运行以下命令重新生成：

   # 重新生成 join 命令 (包含新 token)
   kubeadm token create --print-join-command
   # 重新上传证书并输出新的 certificate-key
   kubeadm init phase upload-certs --upload-certs
   

五、 安装网络插件 (Calico)

参考 Calico 官方文档：

• Project Calico GitHub
• Calico Manifests

1. 下载并配置 Calico

   wget https://raw.githubusercontent.com/projectcalico/calico/refs/heads/master/manifests/calico.yaml
   

   修改 calico.yaml 文件，确保 CALICO_IPV4POOL_CIDR 的值与 kubeadm 初始化时设置的 podSubnet 一致。

   # ...
   - name: CALICO_IPV4POOL_CIDR
     value: "10.244.0.0/16" # 确保此值与 podSubnet 匹配
   # ...
   

   国内环境可按需修改 image 字段，将其指向国内镜像地址。

2. 应用 Calico 清单

   kubectl apply -f calico.yaml
   

   等待所有 calico Pod 正常运行后，kubectl get nodes 应显示所有节点状态为 Ready。

六、 安装常用组件

1. Metrics Server

   参考官方文档：kubernetes-sigs/metrics-server

   kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
   

2. Helm

   参考官方文档：Helm 安装指南

   wget https://get.helm.sh/helm-v4.0.4-linux-amd64.tar.gz
   tar -xf helm-v4.0.4-linux-amd64.tar.gz
   mv linux-amd64/helm /usr/local/sbin/
   

3. Kubernetes Dashboard

   使用 Helm 安装 Dashboard。

   helm repo add kubernetes-dashboard https://kubernetes.github.io/dashboard/
   helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard --create-namespace --namespace kubernetes-dashboard
   

4. 暴露 Dashboard (NodePort)

   创建 Service 以通过节点端口从外部访问 Dashboard。

   apiVersion: v1
   kind: Service
   metadata:
     name: kubernetes-dashboard-kong-proxy
     namespace: kubernetes-dashboard
   spec:
     type: NodePort
     selector:
       app.kubernetes.io/name: kong
       app.kubernetes.io/component: app
     ports:
       - port: 443
         targetPort: 8443
         nodePort: 32443
   

5. 生成 Dashboard 访问令牌

   创建具有管理员权限的服务账号 (ServiceAccount) 并为其生成登录令牌。

   kubectl -n kubernetes-dashboard create serviceaccount admin-user
   
   kubectl create clusterrolebinding admin-user \
     --clusterrole=cluster-admin \
     --serviceaccount=kubernetes-dashboard:admin-user
     
   kubectl -n kubernetes-dashboard create token admin-user --duration=24h
   

   使用生成的令牌登录 Dashboard。