Kubespray 生产级 Kubernetes 集群部署实战指南

Kubespray 生产级 Kubernetes 集群部署实战指南【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubesprayKubespraykubernetes-sigs/kubespray是一套基于 Ansible 的 Kubernetes 集群部署解决方案通过声明式的 Inventory 与 Playbook 即可在裸金属、虚拟机或主流公有云上快速落地生产级、高可用的 Kubernetes 集群。本指南以仓库根目录 README.md 为主线系统讲解 Kubespray 的核心特性、部署前环境检查、Docker / Ansible / Vagrant 三种部署方式、Inventory 结构、核心配置变量与网络插件选型并结合仓库源码cluster.yml、playbooks/cluster.yml、inventory/sample 等深入剖析其部署流程与可定制点。读完本文你将掌握从零搭建、扩容、缩容到升级一个生产级 Kubernetes 集群的完整实战路径。项目概览Kubespray 是什么Kubespray 的目标是Deploy a Production Ready Kubernetes Cluster部署生产就绪的 Kubernetes 集群它由 Kubernetes SIG 维护属于 kubernetes-sigs 组织下的开源项目。其核心思路是将 Kubernetes 集群的组件etcd、kube-apiserver、kube-scheduler、kube-controller-manager、kubelet、kube-proxy、CNI 插件等以 Ansible Role 的形式进行编排安装从而实现可重复、可审计、跨平台的集群交付。从仓库结构可以看到Kubespray 的全部部署逻辑都沉淀在 roles 目录中例如roles/etcd负责 etcd 集群的安装与配置roles/kubernetes/control-plane 与 roles/kubernetes/node分别管理控制平面与工作节点的组件roles/network_plugin承载 Calico、Cilium、Flannel 等网络插件roles/kubernetes-apps负责集群内应用CoreDNS、Metrics Server、Ingress Controller 等的部署。核心特性根据 README.md 的官方描述Kubespray 具备以下关键能力多云与裸金属统一支持可部署到 AWS、GCE、Azure、OpenStack、vSphere、Equinix Metal裸金属、Oracle Cloud Infrastructure实验性以及任意 Baremetal 环境高可用集群支持多控制平面 多 etcd 成员的 HA 拓扑可组合性网络插件、容器运行时、集群内应用均可按需选择主流 Linux 发行版覆盖Debian、Ubuntu、CentOS Stream/RHEL、Fedora、openSUSE、Oracle Linux、AlmaLinux、Rocky Linux 等均有开箱即用的支持持续集成测试通过 tests 目录中的测试用例矩阵持续验证各发行版与插件组合。这些特性使得 Kubespray 既是生产环境快速交付的工具也是学习 Kubernetes 集群各组件装配原理的绝佳参考实现。部署方式一Docker 容器化快速部署Kubespray 官方发布带有完整 Ansible 环境与依赖的容器镜像适合不想在宿主机安装 Python/Ansible 环境的用户。前提是目标机器上已安装 Docker。docker run --rm -it --mount typebind,source$(pwd)/inventory/sample,dst/inventory \ --mount typebind,source${HOME}/.ssh/id_rsa,dst/root/.ssh/id_rsa \ quay.io/kubespray/kubespray:v2.31.0 bash命令含义解析--mount typebind,source$(pwd)/inventory/sample,dst/inventory将当前目录下的样例 Inventory 挂载进容器的/inventory即容器内 Ansible 的-i参数指向的清单路径--mount typebind,source${HOME}/.ssh/id_rsa,dst/root/.ssh/id_rsa将本机 SSH 私钥挂载为容器内/root/.ssh/id_rsa用于免密登录目标节点${HOME}即你的主目录quay.io/kubespray/kubespray:v2.31.0镜像标签对应 Kubespray 版本按需替换bash进入容器内交互式 Shell。进入容器后即可直接运行 Kubespray 的部署 Playbookansible-playbook -i /inventory/inventory.ini --private-key /root/.ssh/id_rsa cluster.yml这里cluster.yml是仓库根目录下的部署入口 Playbook其内容只有一行导入语句将真正的逻辑委托给 playbooks/cluster.yml--- - name: Install Kubernetes ansible.builtin.import_playbook: playbooks/cluster.yml这是 Kubespray 所有场景入口的通用设计仓库根目录下的 cluster.yml、scale.yml、remove-node.yml、upgrade_cluster.yml、reset.yml 等均为薄壳文件实际逻辑统一放在 playbooks 目录中便于版本管理与多入口复用。部署方式二Ansible 原生部署如果希望在宿主机上直接管理集群需要先按 docs/ansible/ansible.md 中的说明安装 Ansible。仓库根目录的 requirements.txt 给出了精确的 Python 依赖清单ansible11.13.0 bcrypt6 cryptography50.0.1 jmespath1.1.0 netaddr1.3.0 passlib1.7.4其中netaddr用于 Ansible 的 IP 网段计算ansible.utils.ipaddrjmespath用于 Jinja2 的json_query过滤器这些是 Kubespray 模板计算 Pod/Service CIDR 时所必需的依赖。Usage标准用法详细的首次集群搭建流程见 docs/getting_started/getting-started.md。核心步骤是创建自己的 Inventory 目录例如inventory/mycluster/编辑inventory/mycluster/inventory.ini定义主机分组按需调整inventory/mycluster/group_vars/下的配置变量执行ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml -b -v \ --private-key~/.ssh/private_key参数说明-i指定 Inventory 文件-b等价于--become即通过 sudo 提权执行对应 README 中非 root 用户运行需配置提权的要求-v提高输出详细程度便于排查问题--private-key指定 SSH 私钥。CollectionAnsible 集合方式若希望把 Kubespray 作为 Ansible Collection 引入现有自动化体系官方提供了 docs/ansible/ansible_collection.md 作为接入指南同时仓库根目录的 galaxy.yml 即 Ansible Galaxy Collection 的元数据清单定义了 collection 的名称、命名空间与内容构成。部署方式三Vagrant 本地开发环境Vagrant 方式适合本地开发、测试或学习场景。首先确认本机已安装 Python 与 pippython -V pip -V若两条命令均能打印出版本号说明环境就绪否则需先安装 Python官方 README 指向 https://www.python.org/downloads/source/。随后按 docs/ansible/ansible.md 安装 Ansible并在仓库根目录直接运行vagrant up仓库根目录的 Vagrantfile 是完整的 Vagrant 编排脚本支持通过环境变量KUBESPRAY_VAGRANT_CONFIG指向自定义的config.rb并内置了多种操作系统的 Vagrant Box 定义如 Flatcar、Ubuntu 20.04/22.04/24.04、AlmaLinux 9、RockyLinux 9、Fedora 39-42、openSUSE、Debian 11/12 等。默认创建 3 台虚拟机$num_instances || 3每台 2048 MB 内存、2 核 CPU。默认网络插件为flannelVagrant 场景与默认的 Calico 不同。注意Vagrant 的详细用法多节点、私有网络、与 Kubespray 的联动见 docs/developers/vagrant.md。构建你自己的 Inventory主机分组与变量体系官方样例 Inventory仓库在 inventory/sample/inventory.ini 提供了标准 HA 拓扑样例3 个控制平面节点 3 个工作节点etcd 与控制平面堆叠stacked etcd# This inventory describe a HA typology with stacked etcd ( same nodes as control plane) # and 3 worker nodes # Configure ip variable to bind kubernetes services on a different ip than the default iface # We should set etcd_member_name for etcd cluster. The node that are not etcd members do not need to set the value, # or can set the empty string value. [kube_control_plane] # node1 ansible_host95.54.0.12 # ip10.3.0.1 etcd_member_nameetcd1 # node2 ansible_host95.54.0.13 # ip10.3.0.2 etcd_member_nameetcd2 # node3 ansible_host95.54.0.14 # ip10.3.0.3 etcd_member_nameetcd3 [etcd:children] kube_control_plane [kube_node] # node4 ansible_host95.54.0.15 # ip10.3.0.4 # node5 ansible_host95.54.0.16 # ip10.3.0.5 # node6 ansible_host95.54.0.17 # ip10.3.0.6关键点[kube_control_plane]控制平面组节点可通过etcd_member_nameetcdN指定其在 etcd 集群中的成员名[etcd:children] kube_control_plane通过children声明 etcd 组由控制平面组派生堆叠拓扑如需独立 etcd 节点可将节点直接放入[etcd]组而非使用 children 继承[kube_node]工作节点组仅运行 kubelet/kube-proxy/容器运行时。关于 Inventory 的分组语义all、k8s_cluster、etcd、kube_control_plane、kube_node、calico_rr等以及动态 Inventory 用法可进一步阅读 docs/ansible/inventory.md 与 docs/ansible/ansible.md。组变量Kubespray 的配置入口Inventory 目录下的group_vars是 Kubespray 的配置中心对应样例位于 inventory/sample/group_vars分两级group_vars/all/作用于所有主机含 etcd如 all.yml基础路径、二进制下载目录、证书目录、containerd.yml容器运行时、docker.yml、offline.yml离线环境以及各云厂商变量文件aws/azure/gcp/openstack/vsphere 等group_vars/k8s_cluster/作用于集群内节点包括 k8s-cluster.yml核心集群参数、kube_control_plane.yml控制平面参数、addons.yml附加组件开关以及每个网络插件独立的配置文件k8s-net-calico.yml、k8s-net-cilium.yml、k8s-net-flannel.yml、k8s-net-kube-ovn.yml等。官方 docs/ansible/vars.md 是全部部署数据变量的权威参考建议在调参前通读。核心集群变量解读以 k8s-cluster.yml 为例几个影响集群形态的关键变量# Kubernetes 配置目录、脚本目录与静态 Pod 清单目录 kube_config_dir: /etc/kubernetes kube_script_dir: {{ bin_dir }}/kubernetes-scripts kube_manifest_dir: {{ kube_config_dir }}/manifests # 证书与 token 存放位置 kube_cert_dir: {{ kube_config_dir }}/ssl kube_token_dir: {{ kube_config_dir }}/tokens # 二进制下载暂存目录约需 1G 磁盘空间 local_release_dir: /tmp/releases # 失败重试的随机间隔秒 retry_stagger: 5 # 选择网络插件cilium, calico, kube-ovn, flannelcni 为通用插件cloud 交由云厂商配置 kube_network_plugin: calico # 是否启用 Multus 多网卡支持 kube_network_plugin_multus: false # Service 网段集群内部服务用须为网络中未占用的地址段 kube_service_addresses: 10.233.0.0/18 # Pod 网段同样必须未被基础设施占用 kube_pods_subnet: 10.233.64.0/18 # 每节点 Pod 子网大小与单节点最大 Pod 数 kube_network_node_prefix: 24 # kubelet_max_pods 默认为 110其中kube_network_node_prefix直接决定集群可容纳的节点规模/24时支持最多约 64 个节点、每节点最多min(254, kubelet_max_pods)个 Pod/25时支持最多约 128 个节点、每节点最多min(126, kubelet_max_pods)个 Pod。IPv6 双栈场景下还可设置kube_service_addresses_ipv6与 Pod 侧 IPv6 网段默认fd85:ee78:d8a6:8607::1000/116。这些变量的底层消费逻辑可以在 roles/kubespray_defaults 的 defaults 中看到Kubespray 在运行各 Role 前会先加载该默认值层。网络插件选择变量README 明确指出网络插件由kube_network_plugin变量决定默认calicoVagrant 场景默认flannel。插件与仓库内对应配置文件的对应关系如下变量取值网络插件仓库参考文档calicoCalico默认docs/CNI/calico.mdciliumCiliumdocs/CNI/cilium.mdflannelFlanneldocs/CNI/flannel.mdkube-ovnKube-OVNdocs/CNI/kube-ovn.mdkube-routerKube-routerdocs/CNI/kube-router.mdmacvlanMacvlandocs/CNI/macvlan.mdmultusMultus配合kube_network_plugin_multusdocs/CNI/multus.mdcustom_cni自定义 CNI自备 Manifestroles/network-plugin/custom_cni从源码结构看各插件的部署逻辑分别位于 roles/network_plugin/calico、roles/network_plugin/cilium、roles/network_plugin/flannel 等目录custom_cni支持通过 Helm Chart 等方式自带 CNI参考 tests/files/custom_cni/README.md 与 tests/files/custom_cni/values.yaml 的示例。深入部署流程cluster.yml 的 Playbook 编排根目录 cluster.yml 导入的 playbooks/cluster.yml 是理解 Kubespray 部署顺序的最佳源码入口。它按阶段编排了多个 play每个 play 依次调用对应的 Ansible Role公共任务与事实收集导入 boilerplate.yml公共前置任务与 internal_facts.yml收集集群内部事实集群准备针对k8s_cluster:etcd组执行 roles/kubespray_defaults加载默认值、roles/kubernetes/preinstall预安装系统依赖、内核参数等、容器引擎container-engine可通过deploy_container_engine关闭与 roles/download下载二进制与镜像可通过skip_downloads跳过安装 etcd导入 install_etcd.yml并通过变量etcd_cluster_setup与etcd_events_cluster_enabled控制 etcd 主集群与事件集群的搭建安装节点对k8s_cluster执行 roles/kubernetes/nodekubelet、kube-proxy 等节点组件安装控制平面对kube_control_plane依次执行 roles/kubernetes/control-planeapiserver/scheduler/controller-manager、roles/kubernetes/clientkubectl/kubeconfig、roles/kubernetes-apps/cluster_roles集群级 RBACkubeadm 与 CNI对k8s_cluster执行 roles/kubernetes/kubeadm、节点标签/污点node-label / node-taint、公共 CRD 与 roles/network_pluginCNI 安装Calico Route Reflector若使用 Calico RR 拓扑对calico_rr组执行 roles/network_plugin/calico/rrWindows 节点补丁对首个控制平面执行 roles/win_nodes/kubernetes_patch安装集群应用对kube_control_plane依次执行外部云控制器external_cloud_controller、策略控制器policy_controller、Ingress 控制器ingress_controller、外部 Provisionerexternal_provisioner以及 roles/kubernetes-apps 主体CoreDNS、Metrics Server、Dashboard、Local Path Provisioner 等均可通过 addons.yml 开关收尾集群 DNS 就绪后对k8s_cluster重新应用resolv.conf相关配置dns_late: true。同时可以注意到 playbook 中大量使用了any_errors_fatal: {{ kubespray_any_errors_fatal | default(true) }}与environment: {{ proxy_disable_env }}前者保证关键步骤失败即整体中止避免不一致状态后者为支持代理环境的节点提供代理禁用上下文——这也解释了 README 中目标节点需能访问互联网拉取镜像的前提。Ansible 运行层面的优化在 ansible.cfg 中也有体现开启了 SSHControlPersist30m连接复用、host_key_checkingFalse、JSON 文件事实缓存缓存目录/tmp超时 86400 秒以及profile_tasks回调可输出每个任务的耗时统计便于定位性能瓶颈。扩缩容与升级scale、remove-node、upgrade 等生命周期 PlaybookKubespray 将集群的日常运维也脚本化为一组薄壳 Playbook与cluster.yml保持相同的目录结构scale.yml → playbooks/scale.yml向集群添加节点。将新节点加入 Inventory 对应分组或改用动态 Inventory后运行即可常用于弹性扩缩容场景remove-node.yml → playbooks/remove-node.yml移除控制平面、工作节点或 etcd 节点。执行流程为先对目标节点进行 drain排空再停止相关 Kubernetes 服务并删除证书最后通过 kubectl 删除节点。通过--extra-vars nodenodename,nodename2指定待删除节点ansible-playbook -i inventory/mycluster/inventory.ini remove-node.yml -b -v \ --private-key~/.ssh/private_key \ --extra-vars nodenodename,nodename2注意当前实现不支持删除第一个控制平面节点或第一个 etcd 节点这两类节点对集群运行至关重要必须保留见 docs/getting_started/getting-started.md。若节点已无法通过 SSH 连接可追加--extra-vars reset_nodesfalse跳过重置步骤也可在 Inventory 中对该主机单独设置reset_nodesfalse。upgrade_cluster.yml集群升级入口具体说明见 docs/operations/upgrades.mdreset.yml重置/清理集群对应 roles/resetrecover_control_plane.yml控制平面故障恢复对应 docs/operations/recover-control-plane.md。这些入口的存在意味着同一套 Inventory 与 group_vars 即可驱动集群的全生命周期管理无需额外编写运维脚本。支持的 Linux 发行版与硬件基线发行版支持矩阵根据 README.mdKubespray 支持当前仓库版本下以下发行版Flatcar Container LinuxDebianBookworm、TrixieUbuntu22.04、24.04、26.04CentOS Stream / RHEL9、10Fedora39、40、41、42Fedora CoreOS见 docs/operating_systems/fcos.mdopenSUSELeap 16.x / TumbleweedOracle Linux9、10Alma Linux9、10Rocky Linux9、1010 为实验性见 docs/operating_systems/rhel.md#rocky-linux-10Kylin Linux Advanced Server V10实验性见 docs/operating_systems/kylinlinux.mdAmazon Linux 2实验性见 docs/operating_systems/amazonlinux.mdUOS Linux实验性见 docs/operating_systems/uoslinux.mdopenEuler实验性见 docs/operating_systems/openeuler.md两条需要注意的约束基于Upstart/SysV init的操作系统不受支持若内核版本低于 4.19务必先阅读 docs/operations/kernel-requirements.md 中的内核要求。从源码看各发行版的差异处理主要落在 roles/bootstrap_os/tasks针对 almalinux/centos/debian/fedora/rocky/ubuntu/opensuse 等分别有独立任务文件以及 roles/container-engine 的各运行时 vars 中。硬件最低要求README 明确给出的硬件基线由 Kubespray 保障运行的最小值实际负载所需资源另当别论控制平面节点内存 ≥ 2 GB工作节点内存 ≥ 1 GB。对于更大规模的集群可参考官方 Building Large Clusters。部署前置检查清单Requirements开始部署前请逐项确认 README.md 中 Requirements 一节的要求Kubernetes 最低版本当前仓库要求最低v1.34.0Ansible 控制端依赖Ansible v2.14、Jinja 2.11 以及python-netaddr必须安装在运行 Ansible 命令的机器上对应 requirements.txt 中的netaddr1.3.0网络访问目标服务器需能访问互联网以拉取容器镜像离线场景请按 docs/operations/offline-environment.md 提前准备离线制品仓库中 contrib/offline 提供了离线镜像与文件的打包/管理脚本IPv4 转发目标服务器需开启 IPv4 转发若使用 IPv6 的 Pod/Service 网段还需开启 IPv6 转发防火墙Kubespray不管理防火墙需要按原有方式自行配置规则为避免部署期问题建议部署前先禁用防火墙提权方式若以非 root 用户运行 Kubespray需在目标服务器配置正确的提权sudo方式并在运行 Playbook 时显式指定-b/--become或设置ansible_become标志。可选的 Ingress 与存储生态Kubespray 在集群就绪后还可一键部署如下附加组件Ingress/LoadBalancerMetalLB裸金属环境的 Service LoadBalancer 提供者详见 docs/ingress/metallb.mdkube-vip 方案见 docs/ingress/kube-vip.md存储插件仓库支持 aws-ebs-csi、azure-csi、cinder-csi、gcp-pd-csi 等云盘 CSI 插件以及 local-path-provisioner、local-volume-provisioner 等本地存储方案详见 roles/kubernetes-apps/csi_driver 与 docs/CSI 目录其他应用cert-manager、CoreDNS、ArgoCD、Helm、Registry 等均可在 addons.yml 中按需开启。支撑文档体系与延伸阅读除了本指南仓库 docs 目录还提供了体系化的运维与进阶文档建议按需查阅入门与对比docs/getting_started/comparisons.mdKubespray 与其他方案对比、docs/getting_started/setting-up-your-first-cluster.mdAnsible 深度docs/ansible/ansible.mdInventory 与 Tags、docs/operations/integration.md与现有 Ansible 仓库集成、docs/ansible/vars.md全部部署变量架构与可靠性docs/advanced/arch.md、docs/operations/ha-mode.mdHA 模式、docs/operations/hardening.md加固、docs/advanced/dns-stack.mdDNS 栈运维操作docs/operations/nodes.md增删节点、docs/operations/upgrades.md升级、docs/operations/offline-environment.md离线部署、docs/operations/mirror.md镜像仓库云厂商接入docs/cloud_providers/aws.md、docs/cloud_controllers/openstack.md、docs/cloud_controllers/vsphere.md 等CI 与测试测试矩阵见 docs/developers/test_cases.md对应 tests 目录中的各发行版 CI 场景文件。总结Kubespray 以一份 Inventory 一套 Ansible Playbook的极简抽象屏蔽了 Kubernetes 组件装配的复杂性同时通过高度可组合的变量体系网络插件、容器运行时、附加组件保留了充分的定制空间。无论是通过 Docker 容器、宿主机 Ansible 还是 Vagrant 拉起第一个集群核心的部署流程都由 playbooks/cluster.yml 统一编排从 etcd 安装、控制平面与节点装配到 CNI 与集群应用的落地环环相扣且每一步都可追踪、可审计。掌握 inventory/sample/group_vars 中的变量体系你就能把 Kubespray 从开箱即用延伸到按生产场景深度定制并配合 scale、remove-node、upgrade 等生命周期 Playbook 长期维护集群。【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考