一、教程环境说明

本教程基于 Rocky Linux 9.x 系统搭建 Kubernetes 1.28+ 稳定版集群，采用主流的 Containerd 容器运行时，适配生产环境标准配置。

1.1 环境硬件要求

• 节点配置：至少 2核CPU、2G内存（生产环境建议4核8G及以上）

• 操作系统：Rocky Linux 9.0/9.1/9.2 全系通用

• 集群架构：1 Master 节点 + N Worker 节点（本教程以单Master双Worker为例）

• 网络要求：所有节点互通，关闭防火墙/放行K8s端口，可联网拉取镜像

1.2 节点规划

注意：所有节点必须全程执行相同的前置配置操作

二、系统前置优化（所有节点执行）

2.1 关闭并禁用防火墙

K8s集群节点间需要大量端口互通，测试/生产环境建议关闭系统防火墙

systemctl stop firewalld
systemctl disable firewalld

2.2 关闭SELinux

SELinux会限制K8s容器权限，必须永久关闭

# 临时关闭
setenforce 0
# 永久关闭（重启生效）
sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config

2.3 关闭系统Swap分区

Kubernetes 强制要求关闭Swap，否则集群无法正常初始化

# 临时关闭
swapoff -a
# 永久关闭，注释swap配置
sed -i '/swap/s/^/#/' /etc/fstab

2.4 设置主机名与hosts解析

分别在对应节点执行主机名设置

# Master节点执行
hostnamectl set-hostname k8s-master

# Worker1节点执行
hostnamectl set-hostname k8s-worker1

# Worker2节点执行
hostnamectl set-hostname k8s-worker2

所有节点统一添加hosts解析

cat >> /etc/hosts << EOF
192.168.10.100 k8s-master
192.168.10.101 k8s-worker1
192.168.10.102 k8s-worker2
EOF

2.5 加载内核模块并开启IP转发

K8s网络依赖iptables网桥转发，需开启内核参数

# 加载网桥模块
modprobe br_netfilter
modprobe overlay

# 配置内核网络参数
cat >> /etc/sysctl.d/k8s.conf << EOF
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

# 生效配置
sysctl --system

三、安装Containerd容器运行时（所有节点）

K8s 1.24+ 已废弃Docker，默认使用Containerd作为容器运行时

3.1 安装依赖包

dnf install -y yum-utils device-mapper-persistent-data lvm2

3.2 添加Docker官方YUM源（含Containerd）

yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

3.3 安装Containerd

dnf install -y containerd.io

3.4 初始化Containerd配置

# 生成默认配置文件
containerd config default > /etc/containerd/config.toml

# 修改配置：使用systemd驱动（K8s强制要求）
sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml

# 重启并开机自启
systemctl restart containerd
systemctl enable containerd

四、安装Kubernetes组件（所有节点）

4.1 配置K8s国内YUM源（阿里云）

官方源速度慢，使用阿里云镜像源提升下载速度

cat > /etc/yum.repos.d/kubernetes.repo << EOF
[kubernetes]
name=Kubernetes
baseurl=https://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el7-x86_64/
enabled=1
gpgcheck=0
repo_gpgcheck=0
gpgkey=https://mirrors.aliyun.com/kubernetes/yum/doc/yum-key.gpg https://mirrors.aliyun.com/kubernetes/yum/doc/rpm-package-key.gpg
EOF

4.2 安装指定版本K8s组件

固定安装 1.28.2 稳定版（可自行替换新版本号）

dnf install -y kubelet-1.28.2 kubeadm-1.28.2 kubectl-1.28.2

4.3 开机自启kubelet

systemctl enable kubelet

说明：kubelet此时启动失败为正常现象，等待集群初始化后自动恢复

五、初始化K8s Master节点（仅Master节点执行）

5.1 执行集群初始化命令

使用阿里云镜像、指定Pod网段、API服务地址，适配国内环境

kubeadm init \
--apiserver-advertise-address=192.168.10.100 \
--image-repository=registry.aliyuncs.com/k8s_gcr \
--kubernetes-version=1.28.2 \
--service-cidr=10.96.0.0/12 \
--pod-network-cidr=10.244.0.0/16

5.2 初始化成功后配置kubectl权限

初始化完成后终端会输出成功提示，执行以下命令配置管理员权限

# 创建.kube目录
mkdir -p $HOME/.kube
# 复制配置文件并授权
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

5.3 保存节点加入命令

初始化成功后，终端会生成类似如下的worker节点加入命令，务必复制保存，后续worker节点需要使用：

kubeadm join 192.168.10.100:6443 --token xxxxxx --discovery-token-ca-cert-hash sha256:xxxxxx

若token过期，可在Master节点执行以下命令重新生成：

kubeadm token create --print-join-command

六、加入Worker节点到集群（所有Worker节点执行）

在每个Worker节点执行上方Master节点生成的join命令

# 示例命令（替换为你自己生成的命令）
kubeadm join 192.168.10.100:6443 --token xxxxxx --discovery-token-ca-cert-hash sha256:xxxxxx

七、部署Calico网络插件（仅Master节点）

K8s集群初始化完成后，节点状态为NotReady，需要部署网络插件实现Pod通信

7.1 应用Calico网络配置

kubectl apply -f https://docs.projectcalico.org/v3.26/manifests/calico.yaml

7.2 查看网络插件部署状态

# 查看所有Pod运行状态
kubectl get pods -n kube-system

# 查看集群节点状态
kubectl get nodes

等待1-3分钟，所有Pod状态变为Running，节点状态变为Ready，集群搭建完成。

八、集群基础验证命令

所有命令均在Master节点执行

# 查看集群节点信息
kubectl get nodes

# 查看集群组件状态
kubectl get cs

# 查看所有命名空间资源
kubectl get all --all-namespaces

# 查看节点详细信息
kubectl describe node 节点名称

九、常见问题排查

9.1 节点NotReady

大概率为网络插件未部署或Calico Pod异常，执行 kubectl get pods -n kube-system 查看异常Pod，删除异常Pod自动重建。

9.2 kubelet启动失败

检查是否关闭Swap、SELinux，确认Containerd的cgroup驱动为systemd。

9.3 镜像拉取失败

本教程已使用阿里云镜像源，若仍失败可手动拉取对应镜像或检查服务器网络。

十、集群重置（报错回滚）

若集群初始化失败需要重新搭建，所有节点执行重置命令

kubeadm reset -f
rm -rf $HOME/.kube
rm -rf /var/lib/etcd