Kubernetes 集群安装与维护指南

在本指南中，我们将详细介绍如何从零开始，在生产环境中部署一个高可用的 Kubernetes 集群。本教程将涵盖从节点的基础环境准备、Containerd 运行时的安装配置，到 Kubernetes 核心组件的部署，最终完成 Master 节点的初始化和 Worker 节点的加入。此外，我们还将提供一套完整的集群重置与节点重新加入的标准操作流程，以应对日常维护中的各种场景。

一、环境规划

本次部署规划一个 Master 节点和一个 Worker 节点。

• Master 节点 (天选5):

  • CPU： i9-13900K
  • 内存： 32GB
  • 硬盘： 1TB
  • 系统： Ubuntu 24.04
  • 已有环境： Docker 27.4.1
  • IP 地址： 192.168.2.125

• Node 节点 (工控机):

  • CPU： (请填写)
  • 内存： 16GB
  • 硬盘： 512GB
  • 系统： Ubuntu 22.04
  • 已有环境： Docker
  • IP 地址： (请填写)

二、通用前置准备 (所有节点)

在 Master 和所有 Node 节点上，都需要执行以下通用步骤以确保环境符合 Kubernetes 的执行要求。

1. 禁用 Swap 分区并加载内核模块

Kubernetes 要求禁用 Swap 以保证 Pod 的性能和稳定性。

# 临时禁用 swap
sudo swapoff -a

# 永久禁用 swap，注释掉 fstab 中的 swap 配置
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

接下来，加载 overlay 和 br_netfilter 内核模块，这对于容器的文件系统和网络桥接至关重要。

# 临时加载模块
sudo modprobe overlay
sudo modprobe br_netfilter

为了让系统重启后自动加载这些模块，我们将其写入配置文件。

# 创建内核模块加载配置文件
sudo tee /etc/modules-load.d/k8s.conf <<EOF
overlay
br_netfilter
EOF

# 使内核参数生效
sudo sysctl --system

2. 安装与配置 Containerd 容器运行时

Containerd 是 Kubernetes 官方推荐的容器运行时。

步骤 1: 安装依赖

sudo apt-get update
sudo apt-get install -y curl gnupg2 software-properties-common apt-transport-https ca-certificates

步骤 2: 添加 Docker / Containerd 的 GPG 密钥与软件源

注意: 如果您已经安装过 Docker，可以跳过此步骤。

• 对于 X86_64 架构:

  sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmour -o /etc/apt/trusted.gpg.d/containerd.gpg
  sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

• 对于 ARM64 架构 (如树莓派):

  sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmour -o /etc/apt/trusted.gpg.d/containerd.gpg
  sudo add-apt-repository "deb [arch=arm64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

  如果 add-apt-repository 命令卡住，可以手动编辑 /etc/apt/sources.list.d/docker.list 文件，添加对应内容。首先查看系统版本代号：

  lsb_release -cs

  然后手动添加源：

  # 示例: sudo nano /etc/apt/sources.list.d/docker.list
  # 添加以下内容 (将 `jammy` 替换为你的版本代号)
  deb [arch=amd64] https://download.docker.com/linux/ubuntu jammy stable

步骤 3: 安装 Containerd

sudo apt-get update
sudo apt-get install -y containerd.io

步骤 4: 配置 Containerd

生成默认配置文件，并修改 cgroup driver 为 SystemdCgroup，这是 Kubernetes 推荐的驱动。

containerd config default | sudo tee /etc/containerd/config.toml >/dev/null 2>&1
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml

修改 sandbox_image (pause 镜像) 地址，避免因网络问题导致集群初始化失败。

# 编辑配置文件
sudo nano /etc/containerd/config.toml

找到 [plugins."io.containerd.grpc.v1.cri"] 下的 sandbox_image，将其值修改为： sandbox_image = "registry.aliyuncs.com/google_containers/pause:3.10"

步骤 5: 重启并启用 Containerd

sudo systemctl restart containerd
sudo systemctl enable containerd

3. 安装 Kubernetes 核心组件

使用阿里云的镜像源来安装 kubeadm、kubelet 和 kubectl。

# 下载 GPG 公钥
curl -fsSL https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.31/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# 添加 Kubernetes APT 软件源
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.31/deb/ /" | 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

至此，所有节点 的基础环境准备工作已全部完成。Worker 节点可以暂时待命，等待 Master 初始化后加入。

三、Master 节点初始化

1. 创建 kubeadm 配置文件

创建一个名为 kubeadm-config.yaml 的配置文件，以便更灵活地控制初始化过程。

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: v1.31.2
# Master 节点的 IP 或一个解析到该 IP 的主机名
controlPlaneEndpoint: "192.168.2.125"
# 指定国内镜像源，加速 Pod 创建
imageRepository: "registry.aliyuncs.com/google_containers"

2. 执行初始化命令

使用该配置文件来初始化 Master 节点。

sudo kubeadm init --config=kubeadm-config.yaml

初始化成功后，您应该会看到类似如下的输出：

kubeadm join ip:6443 --token <token> \
    --discovery-token-ca-cert-hash sha256:<hash>

在节点上运行该命令可以将 Worker 节点加入集群。

按照提示，配置 kubectl：

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

3. 安装 Calico 网络插件

Kubernetes 集群需要一个网络插件 (CNI) 来实现 Pod 之间的通信。这里我们使用 Calico。

kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.1/manifests/calico.yaml

四、Node 节点加入集群

1. 设置 IP 转发 (Node 节点)

确保 Node 节点的 ipv4 ip_forward 功能已启用。

# 临时启用
sudo sysctl net.ipv4.ip_forward=1

# 永久启用
sudo nano /etc/sysctl.conf
# 在文件末尾添加以下内容
net.ipv4.ip_forward=1

2. 执行加入命令

在 Node 节点上，执行之前 Master 初始化成功后生成的 kubeadm join 命令。

# 示例命令
sudo kubeadm join 192.168.2.125:6443 --token <your-token> \
    --discovery-token-ca-cert-hash sha256:<your-hash>

3. 验证集群状态

回到 Master 节点，查看所有节点的状态。

kubectl get nodes

等待 1-2 分钟，当 Calico 相关的 Pod 部署完成后，所有节点的 STATUS 都应该变为 Ready。

五、集群维护与重置

在某些情况下，例如配置错误或需要重新部署，你需要彻底清理并重置集群。

情况一：完全重新部署 Kubernetes 集群

第 1 步：在所有节点上重置 kubeadm

这个命令会尝试撤销 kubeadm init 和 kubeadm join 所做的更改。

sudo kubeadm reset -f

第 2 步：清理残留数据与配置

# 清理 kubectl 配置
sudo rm -rf $HOME/.kube

# 清理 Kubernetes 相关目录
sudo rm -rf /etc/kubernetes/
sudo rm -rf /var/lib/etcd/
sudo rm -rf /var/lib/cni/
sudo rm -rf /var/run/kubernetes/

# 重置 iptables 规则
sudo iptables -F && sudo iptables -X
sudo iptables -t nat -F && sudo iptables -t nat -X
sudo iptables -t raw -F && sudo iptables -t raw -X
sudo iptables -t mangle -F && sudo iptables -t mangle -X

第 3 步：重启相关服务

sudo systemctl restart kubelet
sudo systemctl restart containerd # 或者 docker

完成以上清理后，您就可以从 第三部分 (Master 节点初始化) 开始，重新部署一个全新的集群。

情况二：仅让 Worker 节点重新加入集群

如果只是某个 Worker 节点出现问题，需要脱离集群并重新加入。

第 1 步：在 Master 节点上删除该 Node

# 替换 <node-name> 为你的节点名称
kubectl delete node <node-name>

第 2 步：在故障的 Worker 节点上执行清理

# 禁用 swap
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# 重置 kubeadm 状态
sudo kubeadm reset -f

# 清理残留的文件和配置
sudo rm -rf /etc/kubernetes/
sudo rm -rf /var/lib/etcd/
sudo rm -rf /var/lib/cni/
sudo rm -rf /var/run/kubernetes/
sudo rm -rf /var/lib/kubelet/*
sudo rm -rf /etc/cni/

第 3 步：获取新的加入命令

如果之前的 join 命令中的 token 已过期，可以在 Master 节点上生成一个新的：

kubeadm token create --print-join-command

第 4 步：在 Worker 节点上重新执行 join 命令

使用新生成的命令，让 Worker 节点重新加入集群。

六、Kubectl 常用命令速查