基于kubeadm-playbook快速部署生产级Kubernetes集群实战指南-开发者社区

1. 项目概述与核心价值

如果你正在寻找一种能让你在十分钟内，从几台裸机或虚拟机开始，得到一个功能齐全、生产就绪的Kubernetes集群的方法，那么你找对地方了。kubeadm-playbook这个Ansible项目，正是为了解决“从零到一”部署K8s集群及其核心生态组件这个痛点而生的。我自己在运维和开发混合云平台时，曾多次面临需要快速搭建内部K8s测试或准生产环境的需求。手动照着官方文档一步步操作，不仅耗时，而且容易出错，尤其是在需要集成Ingress、监控、存储等“周边”组件时，更是让人头疼。这个项目就像一位经验丰富的运维工程师，把过去几年社区里关于K8s部署的最佳实践、踩过的坑以及必要的调优参数，全部封装进了一套可重复执行的自动化脚本里。

它的核心哲学非常清晰：拥抱官方，保持简洁。整个项目完全基于kubeadm这个Kubernetes官方推荐的集群引导工具，摒弃了其他复杂安装器（如Kubespray早期版本）的自有逻辑。所有附加组件，如Dashboard、Ingress Controller、Prometheus等，都通过官方的Helm Chart进行部署，绝不引入自定义的、难以维护的“轮子”。这意味着你得到的集群，其核心与社区标准完全一致，升级、排错都有据可循。项目特别适合需要在企业内网（On-Premise）环境，尤其是存在HTTP代理和私有镜像仓库的场景下快速部署K8s。它支持从单节点开发环境到多主高可用（HA）生产集群的灵活伸缩，并且经过了从CentOS/RHEL 7.x到Ubuntu 16.04-20.04，Kubernetes 1.7到1.19等多个版本的长期实战检验。

2. 设计理念与方案选型解析

2.1 为什么坚定选择 Kubeadm 作为基石

在Kubernetes部署工具的“江湖”里，选择很多。早期有Kops（主要面向云）、Kubespray（基于Ansible但早期不依赖kubeadm），还有各种发行版自带的安装器。kubeadm-playbook选择kubeadm作为唯一的核心，是基于以下几个深思熟虑的判断：

首先，正统性与前瞻性。kubeadm是Kubernetes SIG Cluster Lifecycle维护的官方项目，其发展路线与K8s核心版本紧密绑定。使用它意味着你始终走在社区推荐的最佳实践道路上，新特性（如高可用拓扑的改进、kube-proxy模式切换）会最先在这里得到支持。项目README中提到“kubeadm越强大，这个项目就越小”，这恰恰说明了其设计目标：不做kubeadm已经能做好的事，只做它还没覆盖或需要粘合的工作。

其次，自托管（Self-hosted）与容器化。kubeadm默认将控制平面组件（如kube-apiserver、kube-controller-manager）以静态Pod的形式运行，这使得集群管理更加一致和容器化。升级过程（虽然本项目暂不自动化升级）也因此变得更可控，因为本质上就是替换一组镜像。这与一些将组件以系统服务形式安装在宿主机上的方案相比，隔离性和可管理性更好。

最后，复杂度可控。像Kubespray这样的项目功能强大，但抽象层次高，内部逻辑复杂，在定制或排错时学习成本不小。而kubeadm-playbook的定位很明确：它是一套驱动kubeadm完成集群生命周期关键动作（初始化、节点加入）的“胶水”脚本，并负责准备好kubeadm所需的前置条件和后续的“电池”（附加组件）。这种架构让有经验的运维人员能一眼看穿其工作原理，心里有底。

2.2 核心架构与工作流程拆解

整个项目的执行流程可以清晰地分为几个阶段，对应Ansible的不同角色（Role）：

环境准备与重置（reset,common角色）：这是保证部署可重复的关键。它会清理节点上任何旧的K8s安装痕迹（执行kubeadm reset，卸载相关目录），并根据配置安装Docker/containerd、配置内核参数（如net.bridge.bridge-nf-call-iptables）、关闭swap、设置SELinux模式、配置HTTP代理和私有镜像仓库等。这一步确保了所有节点处于一个干净、一致的状态。
控制平面初始化（master角色）：在指定的主节点（primary-master）上运行kubeadm init。项目会生成包含所有用户自定义配置（如Pod网络CIDR、服务CIDR、API Server证书SAN等）的配置文件，然后调用kubeadm。成功后，自动设置本地kubeconfig，方便后续操作。
工作节点加入（node角色）：使用主节点初始化时生成的令牌和发现哈希，在其他节点上执行kubeadm join，将它们纳入集群。
网络与核心插件部署（post_deploy角色）：安装用户选择的CNI网络插件（Flannel、Calico、Weave等）。这是Pod之间能够通信的基础，必须在任何工作负载运行前完成。
生态组件安装（post_deploy角色继续）：这是项目的“增值”部分。通过Helm，按需安装一系列核心附加组件：
- Ingress Controller（通常为Nginx Ingress）：提供集群外部访问入口。
- Dashboard：Web管理界面。
- Metrics Server：为HPA和kubectl top提供资源度量数据。
- 持久化存储支持：根据配置，集成vSphere Cloud Provider、Rook（Ceph）或NFS，创建对应的StorageClass，实现动态卷供应。
- 其他任何可通过Helm Chart安装的组件。
健康检查（cluster_sanity标签）：最后，运行检查任务，确认所有节点状态为Ready，核心Pod全部运行成功，并输出集群访问信息（如Dashboard URL）。

注意：项目通过Ansible的标签（Tags）系统将上述阶段模块化。这意味着你可以灵活地只执行部分操作，例如，仅添加新节点（--tags node）或仅重置集群（--tags reset），这为集群的日常运维提供了极大的便利。

2.3 与同类方案的横向对比

为了更清晰地理解kubeadm-playbook的定位，我们可以将其与几个主流方案进行对比：

特性/项目	kubeadm-playbook	原生 kubeadm 手动操作	Kubespray (kubeadm模式)	Rancher RKE
核心原理	用Ansible自动化`kubeadm`命令及前后置任务	完全手动执行`kubeadm`及所有周边命令	使用Ansible，支持多种部署方式（包括kubeadm）	通过Docker容器部署K8s组件，自有配置格式
学习成本	中等，需了解Ansible和K8s基础	高，需深入理解K8s各组件配置	较高，Ansible Playbook结构复杂	低，UI和CLI工具友好
定制灵活性	高，通过Ansible变量深度定制每个环节	最高，完全手动控制	高，但变量体系庞大	中等，通过cluster.yml配置文件定制
“电池”包含	丰富，集成主流插件（Ingress, PV, 监控等）	无，需全部手动安装	较丰富，但插件版本可能较旧	基础，部分插件需通过Rancher Catalog安装
企业特性支持	强，内置HTTP代理、私有镜像仓库支持	需自行配置，复杂	支持，配置较复杂	支持，有商业版增强
升级支持	不自动化，建议遵循官方kubeadm升级流程	手动按官方指南操作	支持自动化升级	支持通过工具升级
适用场景	追求快速、标准化、生产就绪的On-Prem部署	学习、研究或极度定制化环境	大规模、异构环境、需要全生命周期管理	快速入门、混合云管理、需要商业支持

从对比可以看出，kubeadm-playbook在“快速获得一个功能完备的生产级集群”和“保持与官方工具链对齐”之间取得了很好的平衡。它不像纯手动操作那样繁琐，又避免了像Kubespray那样引入过多的抽象层。对于中小型团队或需要频繁重建集群的CI/CD环境来说，它是一个非常高效的选择。

3. 实战部署：从零搭建一个高可用K8s集群

下面，我将以部署一个3主节点、2工作节点的高可用（HA）集群为例，详细拆解使用kubeadm-playbook的每一步操作和背后的原理。假设我们使用CentOS 7.9作为操作系统。

3.1 前期准备与环境规划

硬件与网络规划：

节点：5台虚拟机或物理机，配置建议2核4GB内存以上。3台作为Master，2台作为Node。
网络：所有节点需在同一二层网络，能互相通信。需要规划好以下网段，且不能与现有网络冲突：
- Pod Network CIDR：10.244.0.0/16(Flannel默认) 或192.168.0.0/16(Calico常用)。
- Service CIDR：10.96.0.0/12。
负载均衡（针对Master HA）：需要为3个Master节点的apiserver提供一个虚拟IP（VIP）。项目支持两种方式：
1. 使用Keepalived：在3个Master节点上部署Keepalived，通过VRRP协议竞选出一个VIP持有者。这是最常用的On-Prem方案。
2. 外部硬件/软件负载均衡器：如果你有F5、HAProxy等，可以配置一个负载均衡器，后端指向3个Master的6443端口。
域名：准备一个内部域名（如k8s.example.com），并配置一个通配符DNS记录*.k8s.example.com指向上述VIP（或首个Master的IP，用于非HA情况）。这将极大简化Ingress服务的访问。

软件准备：

部署机：准备一台可以SSH免密登录所有K8s节点的“部署机”（可以是你的笔记本，也可以是其中一台Master）。在该机器上安装Ansible（2.5+）。
```
# 在CentOS部署机上 sudo yum install epel-release -y sudo yum install ansible python3-pip -y pip3 install --upgrade pyopenssl cryptography # 解决可能出现的密码学库问题
```
SSH互信：在部署机上生成SSH密钥对，并将公钥分发到所有5个节点。
```
ssh-keygen -t rsa -b 2048 ssh-copy-id root@<master1-ip> # 对其他4个节点重复此操作
```
实操心得：生产环境建议使用专门的部署账户而非root，并在Ansible配置中指定become: true来提权。同时，确保所有节点的主机名（hostname）设置正确且唯一，这将是节点在集群中的标识。

3.2 配置详解与关键参数解析

获取项目代码并开始配置：

git clone https://github.com/ReSearchITEng/kubeadm-playbook.git cd kubeadm-playbook cp hosts.example hosts cp -r group_vars/all.example group_vars/all

1. 编辑清单文件 (hosts):这是定义集群拓扑的核心。我们将节点分为三组：primary-master、secondary-masters、kube-node。

[primary-master] master1 ansible_host=192.168.1.101 ip=192.168.1.101 [secondary-masters] master2 ansible_host=192.168.1.102 ip=192.168.1.102 master3 ansible_host=192.168.1.103 ip=192.168.1.103 [kube-node] node1 ansible_host=192.168.1.201 ip=192.168.1.201 node2 ansible_host=192.168.1.202 ip=192.168.1.202 [k8s-cluster:children] primary-master secondary-masters kube-node # 如果使用Keepalived实现VIP，需要定义VIP和网卡 [keepalived:children] primary-master secondary-masters

primary-master：集群初始化节点，kubeadm init在此执行。
ip变量很重要，用于kubeadm配置和Keepalived设置。

2. 编辑主变量文件 (group_vars/all/main.yml):这是配置的“大脑”，变量众多，我们聚焦最关键的几个部分：

# 基础配置 KUBERNETES_VERSION: "1.26.0" # 指定K8s版本 CONTAINER_RUNTIME: "docker" # 或 "containerd" CORP_DNS_DOMAIN: "k8s.example.com" # 你的内部域名 # 网络配置 POD_NETWORK_CIDR: "10.244.0.0/16" SERVICE_CIDR: "10.96.0.0/12" # 高可用配置 MASTER_HA_ENABLED: true MASTER_HA_VIP: "192.168.1.100" # 为3个Master准备的虚拟IP MASTER_HA_VIP_NETMASK: "24" MASTER_HA_VIP_INTERFACE: "eth0" # VIP绑定的网卡 MASTER_HA_METHOD: "keepalived" # 或 "loadbalancer" # 附加组件开关 dashboard_enabled: true ingress_nginx_enabled: true metrics_server_enabled: true helm_enabled: true # 持久化存储（例如vSphere） vsphere_persistent_volumes_enabled: true vsphere_server: "vcenter.example.com" vsphere_user: "administrator@vsphere.local" # 密码建议使用Ansible Vault加密，或通过环境变量传入 # vsphere_password: "{{ lookup('env', 'VSPHERE_PASSWORD') }}" vsphere_datacenter: "DC1" vsphere_datastore: "datastore1"

重要提示：vsphere_password等敏感信息绝对不要明文写在配置文件中。应使用Ansible Vault进行加密：
ansible-vault encrypt_string 'YourSecretPassword' --name 'vsphere_password'
然后将输出的加密字符串粘贴到配置文件中。运行Playbook时需添加--ask-vault-pass参数。

3. 编辑附加组件配置 (group_vars/all/addons.yml):这里可以精细控制每个Helm Chart的安装参数。例如，定制Ingress Nginx：

ingress_nginx: enabled: true namespace: "ingress-nginx" # 使用Helm Chart的values配置 values: | controller: kind: DaemonSet # 改为DaemonSet确保每个节点都有Ingress Pod hostNetwork: true # 使用主机网络，便于直接暴露80/443端口 service: type: ClusterIP # 因为用了hostNetwork，Service类型可设为ClusterIP或None metrics: enabled: true serviceMonitor: enabled: true # 为Prometheus提供监控指标

通过values字段下的YAML字符串，你可以覆盖Chart的默认配置，这是集成高级功能的入口。

3.3 执行部署与关键步骤观察

配置完成后，就可以执行完整的集群部署了：

ansible-playbook -i hosts site.yml

这个命令会触发完整的流程。在输出中，请密切关注以下几个关键阶段：

TASK [common : Preflight check - Kernel modules]：检查并加载必要的内核模块（如br_netfilter,ip_vs等）。如果失败，可能需要手动调整内核或更新系统。
TASK [master : Initialize kubeadm]：这是最核心的一步。你会看到kubeadm init命令的完整参数和输出。成功后会显示加入集群的kubeadm join命令。Playbook会自动保存这个令牌信息供后续节点加入使用。
TASK [post_deploy : Install Pod network]：安装CNI插件。你会看到Flannel或Calico的Pod被创建。必须等到所有kube-system命名空间下的Pod（尤其是coredns) 都进入Running状态后，才能进行后续操作。Playbook中的sanity检查会处理这个等待。
TASK [post_deploy : helm install ingress-nginx]：安装Ingress Controller。安装成功后，你可以通过kubectl get svc -n ingress-nginx查看其服务类型和端口。

部署完成后，运行健康检查确认状态：

ansible-playbook -i hosts site.yml --tags cluster_sanity

这个任务会汇总集群状态，并打印出Dashboard的访问地址和Token。

3.4 访问验证与初步使用

访问Dashboard：
- 根据sanity输出的提示，Dashboard通常可以通过https://<master-vip或master1-ip>:443访问（使用HTTPS）。
- 你需要一个访问令牌。Playbook通常会创建一个具有必要权限的ServiceAccount。获取令牌的命令类似：
```
kubectl -n kubernetes-dashboard describe secret $(kubectl -n kubernetes-dashboard get secret | grep admin-user | awk '{print $1}')
```
- 在登录界面选择“令牌”方式，粘贴即可。
测试Ingress：
- 部署一个简单的测试应用，并创建Ingress规则，将主机名test.k8s.example.com指向该应用。
- 在你的客户端机器上，将test.k8s.example.com解析到VIP或Ingress Controller所在的节点IP。
- 访问http://test.k8s.example.com，应该能看到应用页面。这证明网络和Ingress工作正常。
测试持久化存储（以vSphere为例）：
- 如果启用了vSphere存储，会自动创建一个名为vsphere的StorageClass。
- 创建一个PVC（PersistentVolumeClaim）并挂载到一个Pod。如果PVC能成功绑定（Bound状态），并且Pod能读写卷，则说明存储集成成功。
```
# test-pvc.yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: name: test-pvc spec: storageClassName: vsphere accessModes: - ReadWriteOnce resources: requests: storage: 1Gi
```
```
kubectl apply -f test-pvc.yaml kubectl get pvc test-pvc # 查看状态是否为Bound
```

4. 高级运维与故障排查实录

4.1 集群节点扩容与缩容

扩容（添加新节点）：

编辑hosts文件，在[kube-node]组下添加新节点的信息。
关键：确保只保留你想要操作的目标节点在清单中。一个安全的方法是使用额外的清单文件或通过--limit参数限定范围。但项目推荐的方式是修改hosts文件后，运行专门为节点安装设计的playbook：
```
# 假设hosts文件中现在只有新节点node3的信息在[kube-node]组下 ansible-playbook -i hosts only_nodes_only_install.yml --tags node
```
这个命令只会对新节点执行安装步骤，不会影响现有集群。

缩容（安全移除节点）：

首先，将节点标记为不可调度并驱逐其上运行的Pod：
```
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data
```
编辑hosts文件，在[kube-node]组下仅保留要移除的节点。
执行节点重置Playbook：
```
ansible-playbook -i hosts site.yml --tags node_reset
```
这个任务会执行kubeadm reset，清理节点上的K8s组件。
从集群中删除节点对象：
```
kubectl delete node <node-name>
```

踩坑记录：在移除节点时，务必先执行kubectl drain。直接重置节点会导致其上的Pod被强制终止，如果Pod有副本集（ReplicaSet）管理，虽然会被调度到其他节点，但这个过程可能不够优雅，对于有状态应用可能导致问题。--ignore-daemonsets是因为DaemonSet管理的Pod（如网络插件、监控代理）通常不允许被驱逐，需要额外处理。

4.2 常见问题与解决方案速查表

以下是我在多次使用kubeadm-playbook部署过程中遇到的一些典型问题及解决方法：

问题现象	可能原因	排查步骤与解决方案
`kubeadm init`失败，提示`cgroup driver`不一致	Docker（或containerd）使用的cgroup驱动与kubelet预期的不一致。Docker默认是`cgroupfs`，而kubeadm 1.22+推荐`systemd`。	1. 检查Docker配置：`docker info
节点加入集群失败，提示`connection refused`或证书错误	1. 防火墙未开放6443端口。 2. 主节点`kube-apiserver`服务未正常运行。 3. 加入令牌过期（默认24小时）。	1. 检查主节点防火墙：`sudo firewall-cmd --list-ports`。 2. 在主节点检查API Server Pod：`kubectl get pod -n kube-system
CoreDNS Pod 一直处于`Pending`或`CrashLoopBackOff`状态	1. Pod网络插件（CNI）未成功安装。 2. 节点资源不足（内存/CPU）。 3. 节点有污点（Taint），而Pod没有对应容忍（Toleration）。	1. 检查CNI Pod：`kubectl get pod -n kube-system
Pod 无法解析外部域名或集群内Service域名	1. CoreDNS配置问题。 2. 节点`/etc/resolv.conf`中的DNS服务器不可达。 3. 网络策略（NetworkPolicy）阻止了DNS流量。	1. 测试CoreDNS服务：`kubectl run -it --rm --image=busybox test-dns -- nslookup kubernetes.default`。 2. 检查CoreDNS ConfigMap：`kubectl get configmap coredns -n kube-system -o yaml`。 3. 在Pod内检查`/etc/resolv.conf`。
使用私有镜像仓库，Pod拉取镜像失败 (`ImagePullBackOff`)	1. 节点Docker/containerd未正确配置私有仓库认证。 2. Playbook中`private_registry_*`变量配置有误。 3. 私有仓库证书不被信任。	1. 在节点上手动`docker login`测试。 2. 确认`group_vars/all/main.yml`中的`private_registry_enabled`,`private_registry_url`等变量正确。 3. 对于HTTPS仓库，可能需要将CA证书复制到节点的`/etc/docker/certs.d/<registry-host>/`目录下。
Ingress 服务无法从外部访问	1. Ingress Controller Pod未运行或未使用`hostNetwork`。 2. 节点防火墙未开放80/443端口。 3. 外部DNS未正确解析到Ingress Controller所在节点的IP。	1. 检查Ingress Pod状态和Service类型：`kubectl get all -n ingress-nginx`。 2. 检查Pod是否使用了`hostNetwork: true`，或者其Service类型是否为`LoadBalancer/NodePort`并映射了端口。 3. 在集群内测试Ingress：`kubectl exec -it <pod> -- curl -H "Host: your.ingress.host" http://<ingress-svc>`。
执行Playbook时Ansible报错`Failed to connect to the host via ssh`	1. SSH密钥认证失败。 2. 目标节点防火墙阻止了SSH端口（22）。 3. 目标节点上的SSH服务未运行或配置了禁止root登录。	1. 使用`ssh -v root@<node-ip>`手动测试连接，排查认证问题。 2. 检查部署机的`~/.ssh/known_hosts`文件，旧的密钥记录可能导致冲突，可临时删除对应条目。 3. 确认Ansible inventory文件中的`ansible_host`和`ansible_user`变量正确。

4.3 配置调优与安全加固建议

默认配置是为了通用性，在生产环境中，建议进行以下调优：

分离节点角色：项目鼓励将节点分为master、infra、compute三类。infra节点专门运行Ingress Controller、监控栈（Prometheus、Grafana）、日志收集器等基础设施Pod。可以通过给节点打标签（node-role.kubernetes.io/infra=）和污点（Taint），然后配置Pod的nodeSelector和tolerations来实现。这能避免业务应用与关键基础设施竞争资源。
资源限制与请求：务必为所有通过Helm安装的附加组件（尤其是Prometheus）设置合理的资源请求（requests）和限制（limits）。可以在addons.yml中通过values字段配置。例如，为Prometheus Operator设置内存限制，防止其OOM杀死节点。
网络策略：默认安装的CNI插件（如Calico）支持NetworkPolicy。建议为默认命名空间设置一条“默认拒绝所有入站流量”的策略，然后按需开放。这是实现“零信任”网络的基础。
证书与令牌管理：kubeadm生成的根CA证书默认有效期为10年，但前端证书（apiserver等）可能只有1年。需要定期轮换。Dashboard使用的管理员令牌也应定期更新，或集成更安全的认证方式（如项目计划中的KeyCloak OIDC）。
审计日志：在group_vars/all/main.yml中，可以配置kube_apiserver_audit_*相关变量，启用API Server的审计日志，记录谁在什么时候做了什么操作，这对于安全审计和故障排查至关重要。

5. 项目演进与社区生态

kubeadm-playbook项目本身也在不断进化。从README中提到的规划（LDAP认证、Metrics Server、EFK日志栈）可以看出，社区正在努力填补企业级功能的最后几块拼图。项目的活跃度体现在它对最新Kubernetes版本的快速适配上。

对于使用者而言，参与社区的方式很简单：

报告问题：在GitHub Issues中清晰描述问题、环境、版本和错误日志。
贡献代码：如果你修复了一个bug或增加了一个新功能（例如，支持了新的CNI插件或存储驱动），欢迎提交Pull Request。
分享实践：像本文一样，将你在特定环境（如某云厂商、特定硬件）下的部署经验和调优参数分享出来，对其他人是极大的帮助。

最后，我想分享一点个人体会：自动化工具的价值在于将人从重复、易错的操作中解放出来，但绝不能替代对底层原理的理解。kubeadm-playbook做得很好的一点是，它没有隐藏kubeadm的细节，你总能在Ansible任务的输出中看到它实际执行的命令。我建议在第一次使用后，花时间仔细阅读roles/目录下的任务文件，理解每一个步骤的意图。这样，当遇到问题时，你不仅能“知其然”（按照文档操作），更能“知其所以然”（明白为什么这么操作），从而具备独立排查和解决复杂问题的能力。这才是运维工程师的核心价值所在。