Kubespray 部署前如何用 bootstrap_os 角色为裸机节点安装 Python 并准备 Ansible 执行环境？
【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray
在裸机上部署 Kubernetes 集群之前，节点往往没有安装 Python，Ansible 无法在其上执行任何模块，后续 Kubespray playbook 会直接失败。Kubespray 提供了bootstrap_os角色来解决这个问题：它先配置包管理器、在节点上安装 Python、安装 Ansible 包管理模块所需的系统包，并在需要时把主机名设置为 inventory 中的名字。完成这一步后，这些裸机节点就具备了运行完整cluster.yml部署的前提。适用环境是 README.md 中列出的受支持发行版（Debian Bookworm/Trixie、Ubuntu 22.04/24.04/26.04、CentOS Stream/RHEL 9/10、Fedora 39–42、openSUSE Leap 16.x/Tumbleweed、Alma Linux 9/10、Rocky Linux 9/10 等），且控制机需要能通过 SSH 访问每个节点。
准备条件
- 一台运行 Ansible 的控制机（Kubespray 目录所在位置）。
- 裸机节点运行受支持的 Linux 发行版，控制机可 SSH 登录（bootstrap-os 文档 将 SSH 访问列为必需项）。
- 按 docs/ansible/ansible.md 的建议，把 Kubespray 使用的 Ansible 版本装进 Python 虚拟环境：
VENVDIR=kubespray-venv KUBESPRAYDIR=kubespray python3 -m venv $VENVDIR source $VENVDIR/bin/activate cd $KUBESPRAYDIR pip install -r requirements.txt如果pip install报错Could not find a version that satisfies the requirement ansible==...，说明控制机上的 Python 版本与 Kubespray 支持的 Ansible 版本不兼容。docs/ansible/ansible.md 给出的兼容关系为：
| Ansible 版本 | Python 版本 |
|---|---|
| >=2.18.0, <2.19.0 | 3.11–3.13 |
此外，Kubespray 自带自定义模块（位于library/目录），需要设置环境变量让 Ansible 能找到它们：
export ANSIBLE_LIBRARY=<kubespray_dir>/library创建 bootstrap playbook
docs/operating_systems/bootstrap-os.md 给出的示例 playbook 如下。注意必须关闭 fact gathering，因为此时节点上可能还没有 Python，无法运行事实收集模块：
- hosts: all gather_facts: false # not all hosts might be able to run modules yet roles: - kubespray_defaults - bootstrap_os保存为仓库根目录下的 playbook 文件（如bootstrap.yml），从 Kubespray 目录运行，Ansible 才能按名称解析到roles/kubespray_defaults和roles/bootstrap_os两个角色。
执行顺序说明：kubespray_defaults先加载默认变量，bootstrap_os随后完成节点侧初始化。roles/bootstrap_os/tasks/main.yml 的实际流程是：先用raw方式读取节点的/etc/os-release（这一步不依赖 Python），按ID/VARIANT_ID匹配发行版对应的 vars 和 tasks 文件，然后调用system_packages角色安装系统包，创建~/.ansible/tmp目录（权限 0700），重新收集 facts，最后按需设置主机名。
配置需要调整的变量
以下变量来自 roles/bootstrap_os/defaults/main.yml 和 bootstrap-os 文档，按节点实际情况通过 inventory 的 group_vars、host_vars 或-e覆盖：
override_system_hostname: true（默认值即 true）：角色会把机器主机名设置为 Ansible inventory 中的{{ inventory_hostname }}。如果不想让角色改动节点主机名，将其设为false。http_proxy/https_proxy：节点需要走代理下载软件包时设置，角色会把代理写入包管理器配置。以 Debian/Ubuntu 为例，roles/bootstrap_os/tasks/debian.yml 会先检查/etc/apt/apt.conf中是否已有代理配置，没有才追加Acquire::http::proxy/Acquire::https::proxy条目。centos_fastestmirror_enabled: false：是否启用 CentOS 系 yum 的 fastestmirror 插件。coreos_locksmithd_disable: false：Flatcar 上是否禁用负责滚动重启的locksmithd。
执行 bootstrap
在 Kubespray 目录下（已激活 venv 并设置ANSIBLE_LIBRARY）运行：
ansible-playbook -i <你的inventory文件> bootstrap.yml角色内部的关键行为（以发行版为例说明，具体任务见 roles/bootstrap_os/tasks/debian.yml）：
- Debian 系发行版默认不带 Python：角色先用
raw: which python3探测节点上是否已有 Python，仅在没有时才执行apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y python3-minimal。 - 包安装任务（roles/system_packages/tasks/main.yml）按发行版对应的变量清单安装 Python 之外的系统包，带重试机制（
retries: pkg_install_retries）。 - 主机名设置在
override_system_hostname为真时执行（Flatcar、Fedora CoreOS、SUSE、ClearLinux 等发行版除外）。
验证结果
角色判断节点是否具备 Python 的方式是raw: which python3（探测任务不依赖节点侧 Python）。因此 bootstrap 成功后，可以在任一节点上确认：
ssh <节点地址> 'which python3'能返回 Python 路径即说明节点已具备运行 Ansible 模块的条件。若启用了override_system_hostname: true，同时可以用hostname确认节点主机名已被设置为 inventory 中的名称。
常见问题与限制
- 控制机报 Ansible 版本找不到（
No matching distribution found）：不是网络问题，而是控制机 Python 版本过低或过高，按上文兼容表调整控制机 Python 版本后重装。 - 版本不对齐的其他来源：Ansible collections 或 Python 依赖版本错误同样会导致问题，必要时使用 docs/ansible/ansible.md 中给出的 Kubespray 官方 Docker 镜像（quay.io/kubespray/kubespray）并配合 bind mount 挂载 inventory 与 SSH key 运行，确保工具链版本正确。
- 需要代理的节点务必通过 inventory 变量传入
http_proxy/https_proxy，不要手动在每个节点改配置，否则角色写入的代理规则可能与你的设置不一致。 - 后续用
--tags/--skip-tags过滤任务时（例如跳过 bootstrap_os），文档明确提醒：只有在完全清楚后果时再使用这两个参数。
验证通过后，节点侧的 Python 与包管理环境已就绪，可以进入 Kubespray 的正常部署流程执行cluster.yml。
【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
