ansible 角色文档说明通过 meta/main.yml 文件中的 galaxy_info 字段进行配置,该文件位于角色的根目录下。在 galaxy_info 中定义 author、description、license 和 tags 等属性后,ansible galaxy 或本地工具即可自动读取并展示这些信息,无需编写额外的 markdown 文件。

如何定义角色的基本元数据
基本元数据包括作者、描述和许可证,这些是识别角色身份的核心信息。在 meta/main.yml 中设置 author 为开发者姓名,description 为简短的功能概述,license 为开源协议名称,这些信息会直接显示在角色详情页的头部区域。

--- galaxy_info: author: "devops_team" description: "Configures Nginx web server with SSL support" license: "MIT"
上述代码定义了最基础的三个字段。执行 ansible-galaxy info . 命令时,系统会解析这些 YAML 键值对并输出对应内容。若缺少 author,Galaxy 平台可能无法关联贡献者账号;若 description 为空,列表页将显示默认占位符。确保这些字段使用双引号包裹,避免特殊字符导致 YAML 解析错误。
如何配置角色的依赖与分类标签
依赖关系通过 dependencies 字段声明,分类标签通过 tags 字段实现。在 meta/main.yml 中添加 dependencies 列表,每个元素包含 role 名称或完整 GitHub 路径,Ansible 在执行主角色前会自动安装这些依赖。同时,tags 数组用于搜索过滤,例如添加 web、nginx 标签可使角色出现在相关搜索结果中。

---
galaxy_info:
author: "devops_team"
description: "Configures Nginx web server with SSL support"
license: "MIT"
tags:
- web
- nginx
- ssl
dependencies:
- role: geerlingguy.apache
version: "3.2.0"
此配置展示了依赖与标签的结合使用。当运行包含该角色的 Playbook 时,Ansible 会先检查 geerlingguy.apache 是否已安装,若未安装则从 Galaxy 拉取指定版本。标签 web 和 nginx 使角色在 ansible-galaxy search --tags web 查询中可见。注意 dependencies 必须位于 galaxy_info 同级层级,而非其内部,否则会被忽略。版本号约束建议使用语义化版本,避免使用通配符导致不可控升级。
基于 meta/main.yml 中 galaxy_info 字段的实际验证问题
在 meta/main.yml 中修改 galaxy_info 后,本地 ansible-galaxy info . 命令能立即反映变更,但上传至 Galaxy 平台需重新提交。若 tags 中包含空格或特殊符号,YAML 解析会失败,导致角色无法被索引。验证方法是运行 yamllint meta/main.yml 检查语法,再执行 ansible-galaxy install . 模拟安装过程,确认依赖链无断裂。










