// 此文件由 .github/workflows/gh-pages.yml 生成 - 所有本地更改最终将丢失！ = ansible-role-bootstrap Jonas Pammer opensource@jonaspammer.at; :toc: left :toclevels: 2 :toc-placement!: :source-highlighter: rouge

https://galaxy.ansible.com/jonaspammer/bootstrap[image:https://img.shields.io/badge/available%20on%20ansible%20galaxy-jonaspammer.bootstrap-brightgreen[在 Galaxy 上的版本]] // 非常相关的状态徽章 https://github.com/JonasPammer/ansible-role-bootstrap/actions/workflows/ci.yml[image:https://github.com/JonasPammer/ansible-role-bootstrap/actions/workflows/ci.yml/badge.svg[测试 CI]]

一个用于准备 Linux 系统以便于使用 Ansible 管理的 Ansible 角色。

该角色使用 https://docs.ansible.com/ansible-core/2.16/collections/ansible/builtin/raw_module.html[`ansible.builtin.raw` 模块] 结合自己实现的“操作系统识别系统” 来安装最小所需的包（python 和 sudo） 以允许 Ansible 管理系统。

该角色还确保大多数系统的包缓存是最新的。

在大多数情况下，您希望将此角色与我的 https://github.com/JonasPammer/ansible-role-core_dependencies[`core_dependencies` 角色] 结合使用。

[注意] .DISCLAIMER ===== 此角色是 https://github.com/robertdebock/ansible-role-bootstrap/releases/tag/5.2.12[robertdebock/ansible-role-bootstrap v5.2.12 (2022年1月27日)] （Apache 许可证 2.0，版权归 Robert de Bock 所有（robert@meinit.nl）） 经过各种更改/修复的一个分支。 + 以下是来自 https://github.com/JonasPammer/ansible-role-bootstrap/releases[/releases] 的更改摘要（同时说明了 robertdebock 的问题）：

• 角色本身应该预先填充包管理器缓存： https://github.com/robertdebock/ansible-role-bootstrap/pull/57[robertdebock/ansible-role-bootstrap#57] （在 https://github.com/JonasPammer/ansible-role-bootstrap/pull/43[JonasPammer#43] 中修复； https://github.com/JonasPammer/ansible-role-bootstrap/pull/50[JonasPammer#50] 中修复）
• 将默认的 become 设置为 false，增加能够将 become_user 与 ansible_user 分开定义的能力： https://github.com/robertdebock/ansible-role-bootstrap/issues/63[robertdebock/ansible-role-bootstrap#63] （在 https://github.com/JonasPammer/ansible-role-bootstrap/pull/61[JonasPammer#61] 中修复）
• 将 bootstrap_become_user 的默认值更改为 root
• 在 Ansible 模块步骤中也使用 bootstrap_become_user
• 通过指定 /bin/sh 使角色兼容 podman https://github.com/robertdebock/ansible-role-bootstrap/pull/66[robertdebock/ansible-role-bootstrap#66] （在

  https://github.com/JonasPammer/ansible-role-bootstrap/pull/62[JonasPammer#62] 中修复）

toc::[]

[[meta]] == 🔎 元数据 在下面，您可以找到有关…

• 角色所需的 Ansible 版本
• 角色支持的平台
• 角色的 https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#role-dependencies[角色依赖关系]

.link:meta/main.yml[] [source,yaml]

---

---

galaxy_info: role_name: bootstrap description: 一个用于准备 Linux 系统以便于使用 Ansible 管理的 Ansible 角色。基于 robertdebock 的角色。

author: jonaspammer license: "MIT"

min_ansible_version: "2.9" platforms: # 注意：“actively tested:” 后面的文本表示 Docker 镜像名称 - name: EL # (企业 Linux) versions: - "9" # 测试中：rockylinux9 - name: Fedora versions: - "38" # 测试中：fedora38 - "39" # 测试中：fedora39 - name: Debian versions: - bullseye # 测试中：debian11 - bookworm # 测试中：debian12 - name: Ubuntu versions: - focal # 测试中：ubuntu2004 - jammy # 测试中：ubuntu2204

galaxy_tags: - bootstrap - python - sudo

dependencies: []

[[requirements]] == 📌 要求 // 此角色或 Ansible 本身未涵盖的任何先决条件应在此处提及。 Ansible 用户需要能够 become。

[[variables]] == 📜 角色变量 // 此角色可设置的变量描述应在此处 // 以及可以通过角色参数设置的任何变量。 // 任何从其他角色和/或全局范围（例如 hostvars、group vars 等）读取的变量 // 应在此处也提及。

[source,yaml]

bootstrap_user: root

https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html#term-ansible_user[用户名] 用于连接机器以执行主要的 raw 任务（收集简单事实 / _安装_）。

[source,yaml]

bootstrap_become: false bootstrap_become_user: root

---

传递给大多数实际任务的 become 和 become_user 变量。

bootstrap_become 的默认值设置为 false 因为假设在引导前无法使用 sudo。

[source,yaml]

bootstrap_wait_for_host: false

是否等待主机在 ansible_port（22）上可用。

[source,yaml]

bootstrap_timeout: 3

在失败之前等待远程系统可达/可用的最长秒数。

[[public_vars]] == 📜 此角色定义的事实/变量

每个在此部分列出的变量 在执行此角色时动态定义（只能使用 ansible.builtin.set_facts 覆盖） 并且 不仅在内部使用。

[[tags]] == 🏷️ 标签

// 查看 https://github.com/tribe29/ansible-collection-tribe29.checkmk/blob/main/roles/server/README.md#tags // 了解如何使用标签分组任务的优秀示例

任务标记为以下内容 https://docs.ansible.com/ansible/latest/user_guide/playbooks_tags.html#adding-tags-to-roles[标签]：

[cols="1,1"] |=== |标签 | 目的

2+| 此角色目前没有正式记录的标签。

// | download-xyz // | // | install-prerequisites // | // | install // | // | create-xyz // | |===

您可以使用 Ansible 跳过任务，或仅通过使用这些标签运行某些任务。默认情况下，当未指定标签时运行所有任务。

[[dependencies]] == 👫 依赖项 // 其他角色的列表应在此处， // 以及可能需要为其他角色设置的参数的任何细节， // 或用于其他角色的变量。

[[example_playbooks]] == 📚 示例剧本用法 // 包含如何在剧本中使用此角色来处理常见场景的示例对用户来说也很重要：

[重要]

在使用此角色的剧本中，您必须禁用 gather_facts 属性。 如果此角色成功完成，它将会调用 https://docs.ansible.com/ansible/latest/collections/ansible/builtin/setup_module.html[ ansible 的 setup 模块] 本身（相当于 gather_facts: true 的效果）。

没有任务必须在此角色之前执行。

.最低可行剧本

[source,yaml]

---

• hosts: servers:&provisioned name: 引导由 Ansible 管理的 Linux 机器。 become: false gather_facts: false

  roles:

  • role: jonaspammer.bootstrap

---

====

.更改引导用户（例如，当 root 不是一个选项时）

[source,yaml]

---

• hosts: servers:&provisioned name: 引导由 Ansible 管理的 Linux 机器。 become: false gather_facts: false

  vars: bootstrap_user: "{{ ansible_user }}"

  roles:

  • role: jonaspammer.bootstrap

---

====

.使用 become true（例如，当你知道至少有可用的 sudo 时）

[source,yaml]

---

• hosts: servers:&provisioned name: 引导由 Ansible 管理的 Linux 机器。 become: true gather_facts: false

  vars: bootstrap_user: "{{ ansible_user }}" bootstrap_become: true

  roles:

  • role: jonaspammer.bootstrap

---

====

[[tested-distributions]] == 🧪 测试的发行版

此角色可能在不同的 发行版 上工作，例如 Red Hat 企业 Linux (RHEL)， 尽管没有对该特定发行版进行测试。

// 好的参考可以遵循 - 大多数星标和固定项目来自 geerlingguy: // https://github.com/geerlingguy/ansible-role-docker/blob/master/.github/workflows/ci.yml |=== | 操作系统系列 | 发行版 | 发行版发布日期 | 发行版生命周期终止 | 附带的 Docker 镜像

// https://endoflife.date/rocky-linux | Rocky | Rocky Linux 8 (https://www.howtogeek.com/devops/is-rocky-linux-the-new-centos/[伪装成 RHEL/CentOS 8]) | 2021-06 | 2029-05 | https://github.com/geerlingguy/docker-rockylinux8-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-rockylinux8-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Rocky | Rocky Linux 9 | 2022-07 | 2032-05 | https://github.com/geerlingguy/docker-rockylinux9-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-rockylinux9-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://endoflife.date/fedora (13 个月) | RedHat | Fedora 39 | 2023-11 | 2024-12 | https://github.com/geerlingguy/docker-fedora39-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-fedora39-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://ubuntu.com/about/release-cycle | Debian | Ubuntu 20.04 LTS | 2021-04 | 2025-04 | https://github.com/geerlingguy/docker-ubuntu2004-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-ubuntu2004-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian | Ubuntu 22.04 LTS | 2022-04 | 2027-04 | https://github.com/geerlingguy/docker-ubuntu2204-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-ubuntu2204-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://wiki.debian.org/DebianReleases // https://wiki.debian.org/LTS | Debian | Debian 11 | 2021-08 | 2024-06 (2026-06 LTS) | https://github.com/geerlingguy/docker-debian11-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-debian11-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian | Debian 12 | 2023-06 | 2026-06 (2028-06 LTS) | https://github.com/geerlingguy/docker-debian12-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-debian12-ansible/workflows/Build/badge.svg?branch=master[CI]] |===

[[tested-ansible-versions]] == 🧪 测试的 Ansible 版本

测试的 Ansible 版本尝试与 https://github.com/ansible-collections/community.general#tested-with-ansible[ Ansible 的 community.general 集合的支持模式] 保持相同。 截至撰写本文时为：

• 2.13（Ansible 6）
• 2.14（Ansible 7）
• 2.15（Ansible 8）
• 2.16（Ansible 9）

[[development]] == 📝 开发 // 本项目约定的徽章 https://conventionalcommits.org[image:https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg[约定提交]] https://results.pre-commit.ci/latest/github/JonasPammer/ansible-role-bootstrap/master[image:https://results.pre-commit.ci/badge/github/JonasPammer/ansible-role-bootstrap/master.svg[pre-commit.ci状态]] // image:https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white[pre-commit, link=https://github.com/pre-commit/pre-commit]

[[development-system-dependencies]] === 📌 开发机器依赖项

• Python 3.10 或更高版本
• Docker

[[development-dependencies]] === 📌 开发依赖项 开发依赖项在一个 https://pip.pypa.io/en/stable/user_guide/#requirements-files[pip 需求文件] 中定义，名为 requirements-dev.txt。 Linux 的示例安装说明如下：

---

“可选”：创建一个 python 虚拟环境并为当前 shell 会话激活它

$ python3 -m venv venv $ source venv/bin/activate

$ python3 -m pip install -r requirements-dev.txt

[[development-guidelines]] === ℹ️ Ansible 角色开发指南

请查看我的 https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_GUIDELINES.adoc[ Ansible 角色开发指南]。

如果有兴趣，我还写下了一些 https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_TIPS.adoc[ Ansible 角色开发（最佳）实践]。

[[versioning]] === 🔢 版本管理

版本使用 https://git-scm.com/book/en/v2/Git-Basics-Tagging[标签] 定义， 并被 Ansible Galaxy https://galaxy.ansible.com/docs/contributing/version.html[识别和使用]。

版本不得以 v 开头。

当新标签被推送时，https://github.com/JonasPammer/ansible-role-bootstrap/actions/workflows/release-to-galaxy.yml[ 一个 GitHub CI 工作流] (image:https://github.com/JonasPammer/ansible-role-bootstrap/actions/workflows/release-to-galaxy.yml/badge.svg[发布 CI]) 负责将角色导入到我的 Ansible Galaxy 账户。

[[testing]] === 🧪 测试 每次提交都会在 GitHub 工作流中自动运行测试。

测试主要涉及在不同的 Linux 发行版上运行 https://molecule.readthedocs.io/en/latest/[Molecule] 和使用 <<tested-ansible-versions，多个 Ansible 版本>>。

Molecule 测试还包括一个步骤，该步骤使用 https://github.com/ansible/ansible-lint#readme[`ansible-lint`] 对所有 Ansible 剧本进行检查， 以检查最佳实践和可能需要改进的行为。

要运行测试，只需在命令行中运行 tox。 您可以传递一个可选的环境变量，以定义将由 Molecule 启动的 Docker 容器的发行版：

---

$ MOLECULE_DISTRO=ubuntu2204 tox

有关传递给 MOLECULE_DISTRO 的可能值列表，请查看在 link:.github/workflows/ci.yml[] 中定义的矩阵。

==== 🐛 调试 Molecule 容器

1. 使用选项 MOLECULE_DESTROY=never 运行您的 Molecule 测试，例如：

• [subs="quotes,macros"]

---

$ MOLECULE_DESTROY=never MOLECULE_DISTRO=#ubuntu1604# tox -e py3-ansible-#5# ... TASK [ansible-role-pip : (已省略).] pass:[************************] failed: [instance-py3-ansible-9] => changed=false ... pass:[___________________________________ summary ____________________________________] pre-commit: commands succeeded ERROR: py3-ansible-9: commands failed

---

2. 找到 Molecule 配置的 Docker 容器的名称：

• [subs="quotes"]

---

$ docker ps #30e9b8d59cdf# geerlingguy/docker-debian12-ansible:latest "/lib/systemd/systemd" 8 minutes ago Up 8 minutes instance-py3-ansible-9

---

3. 进入容器的 bash Shell，并进行调试：

• [subs="quotes"]

---

$ docker exec -it #30e9b8d59cdf# /bin/bash

root@instance-py3-ansible-2:/#

• [提示]

  如果您尝试调试的失败发生在 verify.yml 步骤中，而不是实际的 converge.yml， 您可能想知道 ansible 的模块输出（vars），主机（hostvars）和 环境变量已存储在两个文件中，分别位于提供程序和 Docker 机器内部：

• /var/tmp/vars.yml （包含键下的主机变量 hostvars）
• /var/tmp/environment.yml

根据您的需要使用 grep、cat 或进行传输！

• [提示]

  您可能还想知道，上述提到的文件 附加到给定工作流运行的 GitHub CI 装置。 这使得人们能够检查运行之间的差异， 从而帮助调试导致严酷或失败的问题。

image::https://user-images.githubusercontent.com/32995541/178442403-e15264ca-433a-4bc7-95db-cfadb573db3c.png[]

4. 完成调试后，退出并销毁容器：

• [subs="quotes"]

---

root@instance-py3-ansible-2:/# exit

$ docker stop #30e9b8d59cdf#

$ docker container rm #30e9b8d59cdf# 或 $ docker container prune

---

==== 🐛 在本地调试已安装的包版本

尽管这是 tox 3 中的标准功能，https://github.com/tox-dev/tox/pull/2794[现在]仅在 tox 识别 CI 变量的存在时发生。 例如：

---

$ CI=true tox

[[development-container-extra]] === 🧃 提示：容器化理想开发环境

此项目提供了一个“1 次点击容器化开发环境”的定义。

此容器甚至允许在其中运行 Docker 容器（Docker-In-Docker，dind）， 允许执行 Molecule。

要使用它：

1. 确保您符合 link:https://code.visualstudio.com/docs/remote/containers#_system-requirements[ Visual Studio Code 开发容器的系统要求]， 可选地按照该链接页面部分的 安装 节。 + 这包括：安装 Docker，安装 Visual Studio Code 本身，以及安装必要的扩展。
2. 将项目克隆到您的机器上
3. 在 Visual Studio Code 中打开该仓库的文件夹（_文件 - 打开文件夹…_）。
4. 如果您在右下角收到关于开发容器定义存在的提示， 您可以按随附的按钮进入它。 否则，您也可以自己执行 Visual Studio 命令 Remote-Containers: Open Folder in Container（查看 - 命令面板 -> _输入上述命令_）。

[提示]

我建议在这里和那里使用 Remote-Containers: Rebuild Without Cache and Reopen in Container 因为开发容器功能有时在识别 对其定义所做的更改时存在一些问题。 ====

[注意]

您可能需要配置您的主机系统，以便容器可以使用您的 SSH/GPG 密钥。

该过程在 https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials[ 官方开发容器文档的“与容器共享 Git 凭据”一节中进行了描述]。 =====

[[cookiecutter]] === 🍪 CookieCutter

此项目应与 https://github.com/JonasPammer/cookiecutter-ansible-role[最初模板化的 CookieCutter] 保持同步， 使用 https://github.com/cruft/cruft[cruft]（如可能）或手动更改（如有需要） 尽可能保持一致。

.官方的 cruft update 使用示例

---

image::https://raw.githubusercontent.com/cruft/cruft/master/art/example_update.gif[官方的 cruft update 使用示例]

---

==== 🕗 更新日志 当新标签被推送时，仓库维护者将创建适当的 GitHub 发布， 提供相应的变化日志的标题和描述。

[[pre-commit]] === ℹ️ 一般的代码检查和样式约定 一般的代码检查和样式约定 由各种 https://pre-commit.com/[`pre-commit`] 钩子执行，至少在某种程度上会被自动满足球队。

在每次提交时，使用 https://pre-commit.ci/[`pre-commit.ci`] <<note_pre-commit-ci,*>> 自动执行 pre-commit。 拉取请求甚至会被同一工具自动修复， 至少通过自动更改文件的钩子来实现。

[注意]

不必混淆： 虽然某些 pre-commit 钩子能够在某种程度上警告您关于语法或代码中的缺陷（因此 pre-commit 的钩子是测试套件的组成部分）， 但 pre-commit 本身并不运行任何真正的测试套件。 有关测试的信息，请参见 <>。 ====

[提示]

[[note_pre-commit-ci]] 不过，我建议您将 pre-commit 集成到您的本地开发工作流中。

这可以通过进入您克隆项目的目录并运行 pre-commit install 来完成。 这样，git 将在您每次提交时运行 pre-commit 检查， 如果某个钩子触发了警报，提交将被中止。

例如，您还可以通过运行 pre-commit run --all-files 在任何时候执行 pre-commit 的钩子。

== 💪 贡献 https://open.vscode.dev/jonaspammer/ansible-role-bootstrap[image:https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc[在 Visual Studio Code 中打开]] image:https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square[欢迎 PR]

// 包含在 README.adoc 中 :toc: :toclevels: 3

以下部分是通用性质，用于帮助新贡献者。 本项目的实际“开发文档”在 <> 下找到。

=== 前言 首先，感谢您考虑为此项目做贡献。

遵循这些指南有助于传达您尊重开发和管理此开源项目的开发者的时间。 作为回报，他们应在解决您的问题、评估更改和帮助您完成拉取请求时回报这种尊重。

[[cookiecutter--contributing]] === 🍪 CookieCutter 此项目的许多文件来自于 https://github.com/JonasPammer/cookiecutter-ansible-role[最初模板化的 CookieCutter]。

请检查您心目中所做的编辑是否适用于模板， 如果是，请相应地在那里做出更改。 您的更改也可以部分适用于模板 以及部分适用于此项目的某些特定内容， 在这种情况下，您将需要创建多个 PR。

=== 💬 约定提交

普通贡献者不必担心遵循 https://github.com/JonasPammer/JonasPammer/blob/master/demystifying/conventional_commits.adoc[__该规范__] https://www.conventionalcommits.org/en/v1.0.0/[__根据定义__], 因为拉取请求将在项目中被压缩合并成一个提交。 只有核心贡献者，即那些有权推送到该项目分支的人，必须遵循此规范 （例如，以允许自动版本确定和变更日志生成）。

=== 🚀 入门

对该仓库的贡献通过问题和拉取请求（PR）进行。 以下是一些适用于这两者的一般指南：

• 在创建自己的问题之前，请搜索现有问题和 PR。
• 如果您从未参与过贡献，请参见 https://auth0.com/blog/a-first-timers-guide-to-an-open-source-project/[ Auth0 博客上的首次参与指南]，以获取资源和建议，帮助您入门。

==== 问题

问题用于报告问题，请求新功能，或在创建 PR 之前讨论潜在更改。 当您 https://github.com/JonasPammer/ansible-role-bootstrap/issues/new[ 创建新问题] 时，将加载一个模板，该模板将指导您收集和提供我们需要调查的信息。

如果您发现一个问题已覆盖您遇到的问题， 请将自己的重现信息添加到现有问题中而不是创建新问题。 添加一个 https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/[反应] 也可以帮助表明我们的维护人员某一特定问题影响的不止是报告者一人。

==== 拉取请求

对该项目的 PR 总是受欢迎的，可以为您的修复或改进带来下一次发布的快速机会。 https://blog.ploeh.dk/2015/01/15/10-tips-for-better-pull-requests/[一般来说]，PR 应：

• 仅修复/添加所讨论的功能 或 处理广泛的空白/样式问题，而不是两者兼顾。
• 为已修复或更改的功能添加单元或集成测试（如果已有测试套件）。
• 处理一个单一关注点
• 包括仓库中的文档
• 附带完整的拉取请求模板（在创建 PR 时自动加载）。

对于涉及核心功能或需要进行破坏性更改（例如，主要版本发布）的更改， 最好先提出问题以讨论您的提案。

一般来说，我们遵循“分叉和拉取”的 Git 工作流程

1. 将仓库分叉到您自己的 Github 账户
2. 克隆项目到您的机器
3. 在本地创建一个名称简明但描述性强的分支
4. 将更改提交到该分支
5. 遵循特定于本仓库的任何格式和测试指南
6. 将更改推送到您的分叉
7. 在我们的仓库中打开 PR，并遵循 PR 模板，以便我们能够高效地审查更改。

[[changelog]] == 🗒 更新日志 请查看 https://github.com/JonasPammer/ansible-role-bootstrap/releases[本仓库的发布页面] 以获取相应的变化日志。

请注意，本项目遵循语义版本管理。 如果发现小版本更新的意外破坏性更改，请报告。

== ⚖️ 许可证

.link:LICENSE[]

MIT 许可证

版权（c）2022，Jonas Pammer

特此授予任何获得本软件及其相关文档文件（统称“软件”）副本的人，免费使用、复制、修改、合并、出版、分发、再许可和/或销售软件副本的权利，并允许被提供软件的人这样做，但须遵守以下条件：

本版权声明及本许可声明应包含在所有副本或重要部分中。

本软件是“按现状”提供的，不附带任何形式的保证，明示或暗示，包括但不限于对适销性、适用性或不侵权的保证。在任何情况下，作者或版权持有者对因软件或软件的使用或其他交易而产生的任何索赔、损害或其他责任，不承担任何责任，无论是在合同、侵权或其他方面。