用 ansible-galaxy 生成 APB 项目骨架：APB 角色 README 模板全解

本文以 Ansible 源码中随附的 APB README 模板（lib/ansible/galaxy/data/apb/README.md）为主体，逐章讲解 APB（Ansible Playbook Bundle）描述文档的七大标准章节及每节应写入的内容，并结合同目录下的完整 APB 角色骨架（apb.yml.j2、Dockerfile.j2、Makefile.j2、provision/deprovision playbook 等）揭示从 ansible-galaxy role init --type apb 到打包、构建镜像、发布的完整链路。读完后你能独立撰写一份可交付的 APB 说明文档，并理解骨架中每个文件的来龙去脉。

1. 这份 README 模板是什么，放在哪里

本文主角 README.md 不是一份用户手册，而是 APB 角色骨架自带的“默认 README 模板”。当用户执行如下命令时，Ansible 会把整个 data/apb/ 目录复制渲染到目标位置，这份 README 就成为新 APB 项目的初始说明文档：

ansible-galaxy role init my_apb --type apb --init-path ./

CLI 参数可以在 lib/ansible/cli/galaxy.py 的 add_init_options 方法中核对：--type 参数默认值为 default，有效类型包括 'container'、'apb' 与 'network'；--init-path 指定骨架输出目录，默认为当前工作目录。

模板本身是一个纯 Markdown 文件（非 Jinja2 模板，所以没有 .j2 后缀），固定结构包含七个章节，正好对应 APB 作者需要向使用者交代的信息：

1. APB Name —— APB 名称与一句话简介；
2. Requirements —— Ansible 本身或 role 未覆盖的前置条件，例如“若 role 使用了 EC2 模块，应在此说明需要安装 boto 包”；
3. APB Variables —— 可配置变量说明，模板明确要求覆盖 defaults/main.yml、vars/main.yml、apb.yml 中的变量，以及可通过参数传入、从全局作用域（hostvars、group vars 等）读取的变量；
4. Dependencies —— 列出托管在 Galaxy 上的其他 APB/role，并说明相关参数与变量；
5. Example Playbook —— 展示如何调用本 APB（例如以参数传入变量）；
6. License —— 许可证声明（模板默认写的是 BSD）；
7. Author Information —— 作者联系方式或网站（可选章节，不允许 HTML）。

模板原文是简短的占位说明，下一节逐章展开“实际该写什么”，并以骨架中的真实文件为示例。

2. 逐章填写：从模板到可用的 APB 说明文档

2.1 APB Name 与简介

模板第一章要求填写 APB 的简要描述。实际项目中，这段描述应与 apb.yml 的 description 字段保持一致。骨架提供的 apb.yml.j2 模板核心字段如下：

version: '1.0.0'
name: {{ role_name }}
description: {{ description }}
bindable: False
async: optional
metadata:
  displayName: {{ role_name }}
plans:
  - name: default
    description: This default plan deploys {{ role_name }}
    free: True
    metadata: {}
    parameters: []

写 README 时应做到：APB 名称与 apb.yml 的 name 一致（模板中的 {{ role_name }} 占位符会在 galaxy role init 时替换为实际 role 名）；简介中说明该 APB 部署什么服务、默认提供 default plan、是否支持 async（模板默认 optional）；若扩展了 plans（例如增加 offering 计划），README 需同步解释每个计划的差异与适用场景。

2.2 Requirements

模板要求写明“Ansible 本身或 role 未覆盖的前置条件”，并举例：使用 EC2 模块时应声明需要 boto 包。这一章通常包括：

• 运行时依赖：容器内的操作系统/Python 依赖；
• 外部服务：例如 APB 构建与发布需要访问 Kubernetes 集群时，应说明需要 kubeconfig —— 这一点可从 Makefile.j2 中得到印证，其 apb_build 目标将 $(HOME)/.kube:/.kube 挂载进构建容器；
• 镜像仓库：Makefile 模板中的 DOCKERHOST、DOCKERORG 变量从同名环境变量取值，README 应说明构建发布前需要设置这两个环境变量。

2.3 APB Variables

这是 README 的核心章节，模板明确列出了应覆盖的变量来源，对应到骨架文件如下：

变量来源	骨架文件	说明
role 默认值	defaults/main.yml.j2	可覆盖的配置参数，plan 中暴露的参数一般定义在此
role 内部变量	vars/main.yml.j2	role 内部使用的变量
APB 参数声明	apb.yml.j2	各 plan 下 parameters 列表声明向调用方暴露的变量
全局作用域	hostvars / group vars 等	从其他 role 或全局作用域读取的变量须在 README 中注明

README 建议以表格形式呈现（变量名、类型、默认值、含义、是否可由 plan 参数传入）。模板 apb.yml.j2 中 parameters: [] 为空，作者需要把它和 README 变量表一起补全——这是写 README 时必须完成的“成对修改”。

2.4 Dependencies

模板要求列出对其他 Galaxy APB/role 的依赖及参数细节。在 APB 骨架中，依赖声明位于 meta/main.yml.j2 的 dependencies: [] 字段（galaxy_tags 已预置 apb 标签）。实现层面，lib/ansible/galaxy/role.py 中 GalaxyRole.metadata_dependencies 属性会从 meta/main.yml 读取 dependencies 列表并校验其必须是列表类型，requirements 属性则读取 meta/requirements.yml——从源码结构看，README 的依赖说明必须与这两份元数据保持一致，否则安装与校验行为会和文档不符。

2.5 Example Playbook

模板要求给出调用示例，原文给出的形式是：

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

实际撰写时应替换为 APB 的真实调用方式，并说明以参数传入变量的写法。由于 APB 本质是运行在容器内的 role，骨架已提供两个入口 playbook：playbooks/provision.yml.j2 与 playbooks/deprovision.yml.j2，结构一致，仅靠 apb_action 变量区分：

- name: "{{ role_name }} playbook to provision the application"
  hosts: localhost
  gather_facts: false
  connection: local
  vars:
    apb_action: provision
  roles:
    - role: {{ role_name }}

（deprovision 版本对应 apb_action: deproversion 场景，标题为 "deprovision the application"。）README 示例章节应解释：provision/deprovision 两个动作分别做什么、调用方如何携带参数触发。

2.6 License 与 Author Information

模板 License 一节默认写 BSD。注意 meta/main.yml.j2 中注释给出了建议的 SPDX 许可证列表（BSD-3-Clause 默认、MIT、GPL-2.0-or-later、GPL-3.0-only、Apache-2.0、CC-BY-4.0 等），README 与 meta 中的 license 字段应保持一致。Author Information 为可选章节，填写联系方式或网站，模板明确不允许使用 HTML。

3. APB 骨架完整文件清单：让 README 有据可依

除 README.md 外，lib/ansible/galaxy/data/apb/ 目录的完整构成决定了 README 应写什么：

文件	作用
apb.yml.j2	APB 声明：version、name、plans、parameters
Dockerfile.j2	镜像构建模板
Makefile.j2	构建与发布入口
playbooks/provision.yml.j2 / deprovision.yml.j2	provision/deprovision 入口 playbook
tasks/main.yml.j2 / defaults / vars / handlers	标准 role 结构文件
meta/main.yml.j2	Galaxy 元数据，galaxy_tags 预置 apb
tests/test.yml.j2 + tests/ansible.cfg	测试 playbook 与配置（cfg 指定 inventory=./inventory）

Dockerfile.j2 揭示了 APB 的运行时形态：

FROM ansibleplaybookbundle/apb-base

LABEL "com.redhat.apb.spec"=""

COPY playbooks /opt/apb/actions
COPY . /opt/ansible/roles/{{ role_name }}
RUN chmod -R g=u /opt/{ansible,apb}
USER apb

即基于 apb-base 镜像，将 playbooks/ 下两个 playbook 复制到 /opt/apb/actions 作为动作入口，role 本体放入 /opt/ansible/roles/<角色名>，并以非特权用户 apb 运行。这正是 README “Requirements” 章节应向读者解释的运行环境。

Makefile.j2 提供 build_and_push 流程（apb_build → docker_push → apb_push 三步）：

• apb_build：先以 apb-tools:latest 容器执行 prepare 子命令（挂载当前目录、~/.kube 与 docker socket），随后 docker build 出名为 $(DOCKERHOST)/$(DOCKERORG)/$(IMAGENAME):$(TAG) 的镜像；
• docker_push：推送镜像到 registry；
• apb_push：再次运行 apb-tools 容器的 push 子命令，将 APB 注册到 APB 服务。

README 的 Requirements / Example Playbook 章节应与此对应：说明 DOCKERHOST/DOCKERORG 环境变量与三步发布流程的语义。

4. 底层机制：骨架如何生成、APB 角色在安装时如何被识别

从源码结构看，骨架生成逻辑位于 lib/ansible/cli/galaxy.py 的 execute_init：未显式指定 --role-skeleton 时，它会遍历默认骨架目录（apb 类型即 data/apb/），按忽略规则过滤后对每个 .j2 文件用模板数据（role_name、description、author、license 等）渲染——这就是骨架文件中大量 .j2 后缀与 {{ role_name }} 占位符的由来；而 README.md、tests/ansible.cfg 等不带 .j2 后缀的文件则按原样复制。

安装侧同样有 APB 角色的专门处理：lib/ansible/galaxy/role.py 的 GalaxyRole.install() 中，当 Galaxy API 返回的 role_type 为 APP（Container Role）时仅发出警告而不按普通 role 安装：

%s is a Container App role, and should only be installed using Ansible Container

由此可以确认：APB/Container 类角色在 Galaxy 上被标记为 APP 类型，Ansible Galaxy CLI 明确提示应使用容器化工具链（APB tools）而非普通 role 安装器来部署。这也是 README “Requirements” 章节应交代清楚的一个边界：APB 的正常交付路径是构建镜像并注册到 APB 服务，而不是解压进本地 roles 路径。

5. 写作清单

以模板的七章结构为核对清单，完成一份 APB 说明文档时应逐项确认：

1. 名称、简介与 apb.yml 的 name/description 一致，并说明默认 default 计划与 async 行为；
2. Requirements 列出外部依赖（如 boto 类 Python 包、kubeconfig、镜像仓库），与 Makefile.j2 中 ~/.kube 挂载、DOCKERHOST/DOCKERORG 环境变量等事实相符；
3. 变量表覆盖 defaults/main.yml、vars/main.yml、apb.yml plan 参数与全局作用域四类来源，并与 apb.yml 的 parameters 字段一一对应；
4. 依赖与 meta/main.yml 的 dependencies 列表一致；
5. Example Playbook 能解释 provision/deprovision 两种动作的调用方式（对应骨架 playbooks，由 apb_action 变量区分）；
6. License 与 meta 的 license 字段一致；Author Information 不含 HTML。

这份模板篇幅虽短，但七章结构与 APB 角色骨架一一对应：README 写的是骨架文件的“对外契约”。对照 lib/ansible/galaxy/data/apb/ 下的骨架文件、lib/ansible/cli/galaxy.py 的命令实现与 lib/ansible/galaxy/role.py 的安装逻辑，即可得到一份既有可用写作模板、又有源码级佐证的技术全貌。