Kubespray Ansible Collection 安装与使用指南：从 requirements.yml 到生产集群部署

Kubespray Ansible Collection 安装与使用指南：从 requirements.yml 到生产集群部署

【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray

Kubespray 除了直接克隆仓库运行 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.0（version字段）；
• Collection 声明的依赖：安装 Kubespray Collection 后，Ansible 会自动要求存在以下依赖 Collection：

dependencies: 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.yml：

requires_ansible: ">=2.18.0,<2.19.0"

安装前请确认ansible --version落在该区间内。仓库 requirements.txt 为 CI 与本地虚拟环境锁定了完整的 Python 依赖组合（ansible==11.13.0、cryptography==50.0.1、netaddr==1.3.0等），如果依赖安装报错（例如Could not find a version that satisfies the requirement ...），通常意味着本机 Python 版本与 Ansible 版本不兼容，可参考 docs/ansible/ansible.md 中的 Ansible/Python 兼容表，在虚拟环境中安装匹配版本：

VENVDIR=kubespray-venv KUBESPRAYDIR=kubespray python3 -m venv $VENVDIR source $VENVDIR/bin/activate cd $KUBESPRAYDIR pip install -r requirements.txt

3. 第一步：准备 Inventory

文档要求先按 Kubespray 的分组约定建立 inventory。Inventory 结构详见 docs/ansible/inventory.md，核心是三个分组：

• kube_node：运行 Pod 的 Kubernetes 节点；
• kube_control_plane：运行 apiserver、scheduler、controller-manager 的控制面节点；
• etcd：etcd 服务器组，建议至少 3 台以获得容错；若 etcd 组包含在 kube_node 内，则 etcd 节点同样可调度工作负载，反之则互不交叉。

此外还有两个特殊分组：calico_rr（Calico 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_host=95.54.0.12 ip=10.3.0.1 node2 ansible_host=95.54.0.13 ip=10.3.0.2 node3 ansible_host=95.54.0.14 ip=10.3.0.3 node4 ansible_host=95.54.0.15 ip=10.3.0.4 node5 ansible_host=95.54.0.16 ip=10.3.0.5 node6 ansible_host=95.54.0.17 ip=10.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.yml：

collections: - 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 仓库构建 Collection；
• version字段强烈建议锁定到具体 tag（与 galaxy.yml 中的版本对应，如v2.32.0这类标签）或固定分支，而不是长期使用master，以便可复现安装；
• 如果网络受限或你持有本地克隆，可把name替换为本地仓库路径/自托管镜像地址，效果等同。

5. 第三步：安装 Collection

ansible-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，而是一条完整的安装流水线，按顺序执行：

1. 公共准备：导入boilerplate.yml（变量校验与断言）与internal_facts.yml（补充事实收集）；
2. etcd 安装前置（k8s_cluster:etcd主机）：依次应用kubespray_defaults、kubernetes/preinstall、container-engine（受deploy_container_engine控制）、download（受skip_downloads控制）；
3. 安装 etcd 集群：通过 playbooks/install_etcd.yml，由etcd_cluster_setup与etcd_events_cluster_enabled决定主/事件 etcd 集群是否构建；
4. 安装 Kubernetes 节点（k8s_cluster主机）：kubernetes/noderole；
5. 安装控制面（kube_control_plane主机）：kubernetes/control-plane、kubernetes/client、kubernetes-apps/cluster_roles；
6. 调用 kubeadm 并安装 CNI（k8s_cluster主机）：kubernetes/kubeadm、kubernetes/node-label、kubernetes/node-taint、kubernetes-apps/common_crds以及network_plugin（Calico/Cilium/Flannel 等由cluster_network变量决定）；
7. 可选扩展：Calico Route Reflector（calico_rr组）、Windows 节点补丁（kube_control_plane[0]上执行win_nodes/kubernetes_patch）；
8. 安装 Kubernetes 应用（kube_control_plane）：外部云控制器、策略控制器、Ingress 控制器、外部 provisioner 与kubernetes-apps；
9. 收尾：集群 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 文件和上一步创建的 playbook：

ansible-playbook -i INVENTORY --become --become-user=root 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-user=root是必需的，因为安装过程需要修改系统包、systemd 服务与 /etc 下配置。

执行细节上，仓库的 ansible.cfg 展示了 Kubespray 期望的 ssh/defaults 配置（如pipelining=True、host_key_checking=False、gathering = smart、jsonfile 事实缓存）。Collection 安装场景下，建议在自己的项目ansible.cfg或环境变量中保持同样的关键项，并特别注意：Kubespray 携带自定义 Ansible module（library/kube.py），若 Ansible 找不到它们会报错，需设置：

export ANSIBLE_LIBRARY=<kubespray_dir>/library

8. 版本管理与故障排查建议

• 版本锁定：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-user=root 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