教你快速搞定K8S集群搭建，主从架构一步到位不踩坑

综合自Kubernetes官方文档、各大云厂商最佳实践指南及社区常见问题排查总结）

咱们今天的目标就是搭建一个最经典的K8S主从架构集群,一个主节点（Master）带着几个工作节点（Worker Node）一起干活，别怕，跟着步骤走，避开那些常见的“坑”，就能一步到位。

第一步：准备机器和环境（这是地基，必须打牢）

你得先准备几台虚拟机或者物理机,这里我们假设有三台机器，一台当主节点（比如叫k8s-master），两台当工作节点（比如叫k8s-node1, k8s-node2），操作系统推荐用Ubuntu 20.04 LTS或者CentOS 7/8，比较稳定。

关键点1：确保所有机器网络互通。 这是最基本的要求，几台机器之间要能互相ping通，最好给它们设置静态IP地址，免得重启后IP变了导致集群出问题。

关键点2：起个好记的主机名。 像上面说的，分别给三台机器设置好主机名（hostnamectl set-hostname k8s-master），并且在每台机器的/etc/hosts文件里，把三台机器的IP和主机名对应关系都写进去，这样集群内部互相找起来才方便，不会因为DNS解析问题而“失联”。

关键点3：关闭防火墙和Swap。 K8S自己有一套网络和安全规则，默认的防火墙可能会添乱，所以先暂时关掉，Swap（交换分区）也会影响K8S调度，所以也得关。

• 关闭Swap：swapoff -a （临时关闭），还要去/etc/fstab文件里注释掉swap那一行（永久关闭）。
• 关闭防火墙（以CentOS为例）：systemctl stop firewalld 和 systemctl disable firewalld。

关键点4：配置内核参数。 需要加载一些内核模块，并调整系统参数，这个听起来复杂，但照着做就行。

• 运行命令加载模块：modprobe br_netfilter ip_vs ip_vs_rr ip_vs_sh ip_vs_netlink nf_conntrack_ipv4
• 修改系统参数文件（如/etc/sysctl.d/k8s.conf），加入几行配置，然后执行sysctl -p生效，主要目的是让网桥上的流量经过iptables/ipvs的处理，这是K8S网络的基础。

第二步：安装核心“三件套”（容器引擎、kubeadm、kubelet）

K8S运行需要依赖底层容器引擎,最常用的就是Docker，然后安装kubeadm（集群搭建工具）、kubelet（负责启动Pod的节点代理）、kubectl（命令行工具，用来管理集群）。

这里有个大坑：版本兼容性！ 一定要确保Docker、kubeadm、kubelet、kubectl的版本是互相兼容的，最省事的办法是去Kubernetes官方文档查当前稳定版，然后所有组件都安装这个指定版本，比如你决定用v1.28.2，那就全都装v1.28.2，用apt-get install kubelet=1.28.2-00这种格式指定版本号安装，避免自动升级到不兼容的新版。

安装Docker：按照Docker官方指南安装即可，安装后记得配置Docker使用systemd作为cgroup驱动，这和K8S的要求保持一致。

安装K8S组件：需要添加K8S的软件源，然后安装指定版本的kubeadm, kubelet, kubectl，安装完后，记得启动kubelet服务（systemctl enable --now kubelet）。

第三步：用kubeadm初始化主节点（最关键的一步）

一切准备就绪,登录到你的主节点机器上，执行初始化命令。

命令示例：kubeadm init --apiserver-advertise-address=192.168.1.100 --pod-network-cidr=10.244.0.0/16。

• --apiserver-advertise-address：填你主节点的IP地址，这样工作节点才知道去哪找它。
• --pod-network-cidr：这是给Pod分配IP的网段，需要和你后面要安装的网络插件匹配，这里用的是Flannel网络插件的默认网段。

初始化成功后的关键提示一定要存好！ 命令行会输出两条超级重要的信息：

1. 一条是让你用mkdir -p $HOME/.kube和sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config来配置kubectl，这样你就能在主节点上使用kubectl控制集群了。
2. 另一条是kubeadm join ...开头的命令，还带着一个token，这个命令就是用来让工作节点加入集群的，把它复制保存好。

如果初始化失败,别慌，仔细看错误信息，通常它会告诉你哪里出问题了，最常见的原因是前面基础环境没配置好（比如Swap没关、镜像拉取失败），可以用kubeadm reset清理后，排查问题再重试。

第四步：安装网络插件（Pod之间才能通话）

主节点初始化成功后,你运行kubectl get nodes会发现主节点状态是NotReady，这是因为还没装网络插件，集群内部的Pod还无法通信。

安装一个简单的网络插件，比如Flannel：只需要一条命令：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml。

这个yaml文件会从网上拉取Flannel的镜像并部署,等一会儿，再运行kubectl get pods -n kube-system，看到flannel相关的Pod都跑起来后，主节点状态就会变成Ready。

第五步：让工作节点加入集群

现在回到你的两台工作节点机器上,确保第一步里的所有环境准备工作都已经做完了，“三件套”也安装好了（工作节点不需要安装kubectl，但kubelet和kubeadm必须有）。

执行第三步里保存的那个kubeadm join ...命令，如果token过期了，可以在主节点上用kubeadm token create --print-join-command生成一个新的加入命令。

加入成功后,回到主节点，运行kubectl get nodes，你应该就能看到三个节点（一个master，两个worker）的状态都是Ready了。

恭喜！到这里，一个最基础的K8S主从集群就搭建成功了。 你可以尝试部署一个简单的Nginx应用（kubectl create deployment nginx --image=nginx）来测试一下集群是否正常工作。

最后总结一下避坑要点：

1. 环境检查要仔细：网络、主机名、Swap、防火墙，一个都不能马虎。
2. 版本匹配是生命线：所有组件版本必须兼容，强烈建议指定版本号安装。
3. 初始化命令参数别写错：特别是主节点IP和Pod网段。
4. 保存好kubeadm join命令：这是工作节点入场的“门票”。
5. 别忘了装网络插件：否则集群就是个“哑巴”集群。

按照这个流程走下来,避开这些坑，快速搭建一个可用的K8S集群是完全可行的。