Ansible Role 骨架与 README 模板：用 ansible-galaxy role init 创建可发布 Role 的文档规范

本文以 Ansible 仓库中默认 Role 骨架自带的 README.md 模板（lib/ansible/galaxy/data/default/role/README.md）为核心，完整讲解一个 Role 的 README 应当包含的七个标准章节、各章节应写什么内容，并结合源码说明 ansible-galaxy role init 是如何以该模板为骨架生成 Role 目录结构的。读完后你可以规范地创建、填写和发布 Role，并且理解骨架模板中每个 .j2 文件在初始化流程里扮演的角色。

这份 README.md 是什么

在 Ansible 源码中，lib/ansible/galaxy/data/default/role/ 目录是 ansible-galaxy role init 使用的默认 Role 骨架（role skeleton）。执行初始化命令时，Ansible 会遍历这个骨架目录，将其中的文件复制到目标路径，并把 .j2 结尾的模板文件渲染成实际内容。

其中 README.md 是唯一一个不带模板变量、直接原样复制的文件，它规定了新建 Role 的 README 标准骨架：

lib/ansible/galaxy/data/default/role/
├── README.md              # Role 说明文档模板（本文核心）
├── defaults/main.yml.j2   # 默认变量文件
├── vars/main.yml.j2       # 高优先级变量文件
├── tasks/main.yml.j2      # 任务入口
├── handlers/main.yml.j2   # 处理器入口
├── meta/main.yml.j2       # Galaxy 元数据（galaxy_info、dependencies）
├── tests/
│   ├── inventory          # 测试用 inventory（localhost）
│   └── test.yml.j2        # 测试用 playbook
├── files/                 # 待复制文件的存放目录
└── templates/             # 待渲染模板的存放目录

这个目录集合与 GalaxyRole 类中定义的 ROLE_DIRS 常量完全对应，即 ('defaults', 'files', 'handlers', 'meta', 'tasks', 'templates', 'vars', 'tests')，见 GalaxyRole 定义。

Role README 的七个标准章节

模板 README.md 按顺序给出了七个章节，每个章节都附带了“这一节应该写什么”的撰写指南。下面逐一继承原文并展开。

Role Name：角色名称与简述

模板开头要求以简短的段落描述 Role 的用途（原文：“A brief description of the role goes here”）。这一段是用户在 Galaxy 上浏览 Role 列表时最先看到的内容，应与 meta/main.yml 中的 description 字段保持一致，避免“文档说 A、元数据说 B”的情况。

Requirements：前置条件

这一节用于列出 Ansible 本身或该 Role 无法覆盖的前置条件。原文给出了一条具体示例：如果 Role 使用了 EC2 模块，就应该在此处说明需要 boto 包。

典型写法可以覆盖三类内容：

• 控制端（controller）所需的 Python 依赖，如某些云模块所需的 SDK；
• 目标主机（managed node）上的系统要求，如最低发行版、必须安装的软件包；
• 权限要求，如需要 root 或 sudo 权限、需要特定网络访问（例如能否访问某个仓库）。

Role Variables：变量说明

原文指出：所有可设置的变量都应在这里描述，具体包括三类来源——

1. defaults/main.yml 中的默认变量；
2. vars/main.yml 中的变量；
3. 可以通过 Role 参数（playbook 中 roles 项直接传参）设置的变量。

此外，凡是从其他 Role 或全局作用域读取的变量（hostvars、group vars 等）也必须在此说明。这是因为这些依赖不会在 Role 内部声明，外部使用者只能通过 README 才能发现。

骨架中这两个变量文件初始都是空模板，分别位于 defaults/main.yml.j2 和 vars/main.yml.j2，初始化后各自渲染为 # defaults file for <rolename> / # vars file for <rolename> 的占位注释。

Dependencies：依赖的其他 Galaxy Role

原文要求在此列出该 Role 依赖的其他 Galaxy Role，并补充细节：其他 Role 可能需要设置的参数、或本 Role 从其他 Role 中使用的变量。

这些依赖的机器可读版本写在 meta/main.yml 的 dependencies 字段中。骨架模板 meta/main.yml.j2 默认输出 dependencies: []，并在初始化时根据传入的依赖列表逐行渲染出 - <dependency> 条目。README 的 Dependencies 章节相当于这个字段的“人读版”，用于解释机器描述无法表达的参数细节。

Example Playbook：使用示例

原文给出的示例 playbook 片段是：

- hosts: servers
  roles:
     - { role: username.rolename, x: 42 }

它演示了通过短格式为 Role 传参（x: 42 会作为 Role 变量注入）。实践中这一节应给出一个可复制运行的最小 playbook：目标主机组、Role 的完整限定名（username.rolename）、以及最关键的自定义变量。骨架自带的测试 playbook tests/test.yml.j2 演示了最简形式——对 localhost 应用该 Role：

- hosts: localhost
  remote_user: root
  roles:
    - {{ role_name }}

初始化后 {{ role_name }} 会被替换为实际 Role 名，配合同目录的 tests/inventory（内容仅一行 localhost）即可本地跑通 Role。

License：许可证

模板默认填写 BSD。与之对应，meta/main.yml 模板中的 license 字段默认建议值为 BSD-3-Clause，模板注释中列出的其他可选值还包括 MIT、GPL-2.0-or-later、GPL-3.0-only、Apache-2.0、CC-BY-4.0 等 SPDX 许可证 ID（见 meta/main.yml.j2 注释）。发布前应确保 README 声明的许可证与元数据及代码 LICENSE 文件三者一致。

Author Information：作者信息

这是一个可选章节，用于放置作者联系方式或网站。原文明确限制：不允许 HTML。

骨架如何被生成：init 流程中的 README 与 .j2 模板

理解 README 模板的“静态”属性，需要看初始化入口 GalaxyCLI.execute_init（lib/ansible/cli/galaxy.py）：

• 命令形式为 ansible-galaxy role init <path>，可搭配 --force、--offline 选项；--role-skeleton 可指向自定义骨架目录，不提供时使用内置默认骨架，即 Galaxy 类计算出的 default_role_skeleton_path（lib/ansible/galaxy/init.py）。--type 选项可切换到其他 Role 类型骨架，默认路径对应 data/default/role；
• 初始化过程用 os.walk 遍历骨架目录，按 GALAXY_ROLE_SKELETON_IGNORE 正则跳过被忽略的文件；默认骨架的忽略表达式为 ['^.*/.git_keep$']（用于跳过 files/、templates/ 等空目录中的占位文件）；
• 对每个 .j2 文件，用 template_data（包含 role_name、author、company、description 等初始化参数）做 Jinja2 渲染后落盘；而 README.md 没有 .j2 后缀，因此按原样复制——这就是为什么新 Role 的 README 永远带着“A brief description of the role goes here”这样的撰写提示，等待作者填写。

从“模板骨架”到“可安装 Role”：与 Galaxy 安装机制的衔接

README 写完、元数据填好后，Role 才能被其他团队通过 Galaxy 安装。从 GalaxyRole 类 可以看到几个关键约定，恰好解释了模板各章节背后的机制：

• META_MAIN 只认 meta/main.yml（或 main.yaml），metadata 属性会逐路径加载它——这就是 README 中“依赖、版本、许可证”等信息的权威来源；
• metadata_dependencies 属性强制要求 dependencies 是一个列表，否则抛出 AnsibleParserError（见 role.py），所以 meta/main.yml 里 dependencies 的空值必须写成 [] 而不是空行；
• remove() 方法在删除 Role 前会以“该路径下存在 meta/main.yml”作为安全校验，避免误删普通目录；
• 安装时会写入 meta/.galaxy_install_info（META_INSTALL 常量），记录版本与安装时间，供 ansible-galaxy role list / info 查询使用。

实操清单：把骨架变成完整 Role 文档

1. 执行 ansible-galaxy role init <role_name> 生成骨架，目录结构即上文所列的 8 个子目录加 README.md；
2. 替换 README.md 七个章节的占位文字：简述、前置条件（如 boto 之于 EC2 模块）、变量表（覆盖 defaults/、vars/、Role 参数及 hostvars/group vars 依赖）、Galaxy 依赖说明、可运行 playbook 示例、许可证、作者信息；
3. 填写 meta/main.yml.j2 渲染出的 galaxy_info：author、description、company、license、min_ansible_version、galaxy_tags（单个单词、字母数字组成，每 Role 最多 20 个 tag），以及 dependencies；
4. 在 tests/test.yml + tests/inventory 的最小环境里验证 Role 可运行，README 的 Example Playbook 章节就以此为蓝本扩写。

小结

lib/ansible/galaxy/data/default/role/README.md 看似只有一页占位文字，实则是 Ansible 为每个新建 Role 强制提供的文档契约：它把“Role 文档该写什么”固化进了 ansible-galaxy role init 的骨架输出里。配合 meta/main.yml.j2 的元数据模板、tests/ 的最小验证环境，以及 GalaxyRole 对 meta/main.yml、dependencies、安装信息的解析约定，一条 Role 从本地创建、文档编写到 Galaxy 发布安装的完整链路在此闭环。规范地填写这七个章节，是保证 Role 可被他人检索、理解并正确集成的最低成本投入。