Kubespray Ansible Collection 安装与使用指南从 requirements.yml 到生产集群部署【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubesprayKubespray 除了直接克隆仓库运行 playbook 之外还可以作为标准 Ansible Collection 被安装和引用。本篇基于仓库文档docs/ansible/ansible_collection.md展开讲清 Collection 的坐标与依赖、五步安装流程requirements.yml 配置、ansible-galaxy安装、playbook 编写、ansible-playbook执行的完整操作并结合仓库中的 galaxy.yml、meta/runtime.yml 与 playbooks/cluster.yml 等源码说明该 Collection 安装到系统后实际加载了哪些内容、执行时内部做了什么帮助你把 Kubespray 以 Collection 方式纳入自己的 Ansible 工作流。1. Collection 坐标、版本与依赖来自 galaxy.yml 的事实Kubespray 的 Collection 元数据定义在仓库根目录的 galaxy.yml 中这是判断“装了什么”的权威来源命名空间与名称kubernetes_sigs.kubespray因此 playbook 中以 FQCN 引用时写作kubernetes_sigs.kubespray.cluster当前版本2.32.0version字段Collection 声明的依赖安装 Kubespray Collection 后Ansible 会自动要求存在以下依赖 Collectiondependencies: ansible.utils: 2.5.0 community.crypto: 2.22.3 community.general: 7.0.0 ansible.netcommon: 5.3.0 ansible.posix: 1.5.4 community.docker: 3.11.0 kubernetes.core: 2.4.2这些依赖覆盖了 Kubespray 用到的加密模块community.crypto、通用模块community.general、Docker 相关模块community.docker以及 Kubernetes API 操作模块kubernetes.core。galaxy.yml 中的manifest.directives还规定了打包时的文件取舍递归排除tests/**递归包含roles/**/files/*即发布产物中不包含测试目录但会带上各 role 的 files 资源。2. 前置条件Ansible 版本要求Kubespray 对控制端 Ansible 版本有明确约束定义在 meta/runtime.ymlrequires_ansible: 2.18.0,2.19.0安装前请确认ansible --version落在该区间内。仓库 requirements.txt 为 CI 与本地虚拟环境锁定了完整的 Python 依赖组合ansible11.13.0、cryptography50.0.1、netaddr1.3.0等如果依赖安装报错例如Could not find a version that satisfies the requirement ...通常意味着本机 Python 版本与 Ansible 版本不兼容可参考 docs/ansible/ansible.md 中的 Ansible/Python 兼容表在虚拟环境中安装匹配版本VENVDIRkubespray-venv KUBESPRAYDIRkubespray python3 -m venv $VENVDIR source $VENVDIR/bin/activate cd $KUBESPRAYDIR pip install -r requirements.txt3. 第一步准备 Inventory文档要求先按 Kubespray 的分组约定建立 inventory。Inventory 结构详见 docs/ansible/inventory.md核心是三个分组kube_node运行 Pod 的 Kubernetes 节点kube_control_plane运行 apiserver、scheduler、controller-manager 的控制面节点etcdetcd 服务器组建议至少 3 台以获得容错若 etcd 组包含在 kube_node 内则 etcd 节点同样可调度工作负载反之则互不交叉。此外还有两个特殊分组calico_rrCalico Route Reflector 高级网络场景与bastion节点不直接可达时的跳板机。k8s_cluster分组由 Kubespray 内部动态定义为kube_node、kube_control_plane与calico_rr的并集用于承载整集群变量group_vars/k8s_cluster/*.yml。一个完整的 inventory 示例如下摘自 docs/ansible/inventory.md## Configure ip variable to bind kubernetes services on a ## different ip than the default iface node1 ansible_host95.54.0.12 ip10.3.0.1 node2 ansible_host95.54.0.13 ip10.3.0.2 node3 ansible_host95.54.0.14 ip10.3.0.3 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] node1 node2 [etcd] node1 node2 node3 [kube_node] node2 node3 node4 node5 node6仓库内也提供了现成的 inventory 样例目录inventory/sample/、inventory/local/可直接参照其inventory.ini与group_vars/组织结构。变量定制层面推荐通过 inventory 的group_vars/host_vars或-e foo.yml注入具体分层优先级见 docs/ansible/ansible.md。4. 第二步在 requirements.yml 中声明 Kubespray按文档 docs/ansible/ansible_collection.md 的写法将 Kubespray 以 git 源形式加入requirements.ymlcollections: - name: https://github.com/kubernetes-sigs/kubespray type: git version: master # use the appropriate tag or branch for the version you need实操要点type: git表示ansible-galaxy collection install会直接从 git 仓库构建 Collectionversion字段强烈建议锁定到具体 tag与 galaxy.yml 中的版本对应如v2.32.0这类标签或固定分支而不是长期使用master以便可复现安装如果网络受限或你持有本地克隆可把name替换为本地仓库路径/自托管镜像地址效果等同。5. 第三步安装 Collectionansible-galaxy install -r requirements.yml执行后 Kubespray 会被安装到本机 Collection 目录默认为~/.ansible/collections/ansible_collections/kubernetes_sigs/kubespray并且 galaxy.yml 中声明的dependencies列表里的各 Collection 会被一并解析安装。安装完成后可用ansible-galaxy collection list | grep kubespray验证其存在与版本。6. 第四步编写安装 playbook创建一个最小 playbook例如playbook/install-k8s.yml- name: Install Kubernetes ansible.builtin.import_playbook: kubernetes_sigs.kubespray.cluster这条import_playbook指令会加载 Collection 内部的cluster.ymlplaybook其真实内容对应仓库中的 playbooks/cluster.yml。从该文件可以看到Collection 安装入口并非单个 role而是一条完整的安装流水线按顺序执行公共准备导入boilerplate.yml变量校验与断言与internal_facts.yml补充事实收集etcd 安装前置k8s_cluster:etcd主机依次应用kubespray_defaults、kubernetes/preinstall、container-engine受deploy_container_engine控制、download受skip_downloads控制安装 etcd 集群通过 playbooks/install_etcd.yml由etcd_cluster_setup与etcd_events_cluster_enabled决定主/事件 etcd 集群是否构建安装 Kubernetes 节点k8s_cluster主机kubernetes/noderole安装控制面kube_control_plane主机kubernetes/control-plane、kubernetes/client、kubernetes-apps/cluster_roles调用 kubeadm 并安装 CNIk8s_cluster主机kubernetes/kubeadm、kubernetes/node-label、kubernetes/node-taint、kubernetes-apps/common_crds以及network_pluginCalico/Cilium/Flannel 等由cluster_network变量决定可选扩展Calico Route Reflectorcalico_rr组、Windows 节点补丁kube_control_plane[0]上执行win_nodes/kubernetes_patch安装 Kubernetes 应用kube_control_plane外部云控制器、策略控制器、Ingress 控制器、外部 provisioner 与kubernetes-apps收尾集群 DNS 就绪后在k8s_cluster上应用 resolv.conf 变更resolvconftag。每个 play 都设置了any_errors_fatal: {{ kubespray_any_errors_fatal | default(true) }}并注入proxy_disable_env这解释了为什么安装中断后建议整批重跑而非跳过失败主机。值得注意的是 roles/kubespray-defaults/tasks/main.yml旧 role 名kubespray-defaults已被标记为 deprecated任务中会打印 “kubespray-defaults is deprecated, switch to kubespray_defaults” 并兼容转发到新 role因此在自己的 playbook 中直接引用时请使用kubespray_defaults。7. 第五步执行安装将INVENTORY与PLAYBOOK替换为你的 inventory 文件和上一步创建的 playbookansible-playbook -i INVENTORY --become --become-userroot PLAYBOOK对应克隆仓库运行方式的等价命令形如ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml -b -v见 docs/getting_started/getting-started.md。仓库根目录的 cluster.yml 本身仅有一行import_playbook: playbooks/cluster.yml而--become --become-userroot是必需的因为安装过程需要修改系统包、systemd 服务与 /etc 下配置。执行细节上仓库的 ansible.cfg 展示了 Kubespray 期望的 ssh/defaults 配置如pipeliningTrue、host_key_checkingFalse、gathering smart、jsonfile 事实缓存。Collection 安装场景下建议在自己的项目ansible.cfg或环境变量中保持同样的关键项并特别注意Kubespray 携带自定义 Ansible modulelibrary/kube.py若 Ansible 找不到它们会报错需设置export ANSIBLE_LIBRARYkubespray_dir/library8. 版本管理与故障排查建议版本锁定Kubespray 的版本号与 git tag 一一对应仓库通过 scripts/galaxy_version.py 基于git describe --tags推导 galaxy 版本因此requirements.yml中version字段直接填 tag 即可获得与 CHANGELOG.md 条目一致的版本依赖版本问题装错 Ansible 或 Collection 版本是常见问题docs/ansible/ansible.md 的 “Troubleshooting Ansible issues” 一节给出了排查路径容器化替代方案如果难以在控制端凑齐匹配的 Ansible/Python 依赖Kubespray 提供预构建的 Docker 镜像见 docs/ansible/ansible.md 末尾的 bind mount 示例将 inventory 与 SSH 密钥挂载进容器后在容器内运行 playbook可完全绕开本地 Collection 安装的环境问题标签执行安装过程中可按 tag 精细控制完整 tag 列表见 docs/ansible/ansible.md例如只准备镜像不上传--tags download --skip-tags upload,upgrade。文档同时提醒仅在完全理解后果时使用--tags/--skip-tags。9. 小结作为 Ansible Collection 使用 Kubespray 的完整路径是准备符合kube_node/kube_control_plane/etcd分组约定的 inventory → 在requirements.yml中以 git 源锁定版本 →ansible-galaxy install -r requirements.yml→ 用ansible.builtin.import_playbook: kubernetes_sigs.kubespray.cluster编写安装 playbook →ansible-playbook -i INVENTORY --become --become-userroot PLAYBOOK执行。Collection 入口最终展开为 playbooks/cluster.yml 定义的多 play 流水线preinstall → etcd → node → control plane → kubeadm/CNI → apps而 galaxy.yml 与 meta/runtime.yml 则分别约束了 Collection 依赖与 Ansible 版本边界这两处文件是排障时的第一检查点。【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考