Galaxy 开发指南

您可以在 Galaxy 上托管集合（collections）和角色（roles）以便与 Ansible 社区共享。Galaxy 内容被格式化为预打包的工作单元，例如 角色和 集合。您可以为配置基础设施、部署应用程序以及您每天执行的所有任务创建角色。更进一步，您可以创建集合，提供一个全面的自动化包，其中可能包含多个 playbook、角色、模块和插件。

为 Galaxy 创建集合

集合是 Ansible 内容的一种分发格式。您可以使用集合来打包和分发 playbook、角色、模块和插件。您可以通过 Ansible Galaxy 发布和使用集合。

有关如何创建集合的详细信息，请参阅 开发集合。

为 Galaxy 创建角色

使用 init 命令来初始化新角色的基础结构，从而节省创建角色所需的各种目录和 main.yml 文件的时间

$ ansible-galaxy role init role_name

上述操作将在当前工作目录中创建以下目录结构

role_name/
    README.md
    defaults/
        main.yml
    files/
    handlers/
        main.yml
    meta/
        main.yml
    tasks/
        main.yml
    templates/
    tests/
        inventory
        test.yml
    vars/
        main.yml

如果您想为该角色创建仓库，则仓库根目录应为 role_name。

强制执行

如果当前工作目录中已经存在与角色名称匹配的目录，则 init 命令将导致错误。要忽略该错误，请使用 --force 选项。Force 将创建上述子目录和文件，并替换任何匹配的内容。

启用容器

如果您正在创建“容器启用（Container Enabled）”角色，请向 ansible-galaxy role init 传递 --type container。这将创建与上述相同的目录结构，但会填充适用于容器启用角色的默认文件。例如，README.md 的结构略有不同，.travis.yml 文件使用 Ansible Container 测试角色，且 meta 目录包含一个 container.yml 文件。

使用自定义角色骨架

可以按如下方式提供自定义角色骨架目录

$ ansible-galaxy role init --role-skeleton=/path/to/skeleton role_name

当提供骨架时，init 将

  • 将所有文件和目录从骨架复制到新角色

  • 在 templates 文件夹之外发现的任何 .j2 文件都将被作为模板进行渲染。目前唯一有用的变量是 role_name

  • .git 文件夹和任何 .git_keep 文件将不会被复制

或者，可以使用 ansible.cfg 来配置角色骨架和要忽略的文件。

[galaxy]
role_skeleton = /path/to/skeleton
role_skeleton_ignore = ^.git$,^.*/.git_keep$,^\./CLAUDE\.md$

role_skeleton_ignore 选项是一个正则表达式列表，用于匹配要忽略的文件和目录。正则表达式与目录名称和相对文件路径进行匹配。骨架目录根中的文件具有路径前缀 ./（例如 ./README.md），而骨架中某个目录下的文件则使用目录名称作为前缀（例如 plugins/README.md）。

Galaxy 身份验证

使用 import、delete 和 setup 命令在 Galaxy 网站上管理您的角色需要以 API 密钥形式进行身份验证，您必须在 Galaxy 网站上创建账户。

要创建身份验证令牌

  1. 点击 Collections > API Token。

  2. 点击 Load Token 然后复制它。

  3. 将您的令牌保存到 GALAXY_TOKEN_PATH 中设置的路径。

导入角色

import 命令要求您使用 API 令牌进行身份验证。您可以将其包含在 ansible.cfg 文件中，或使用 --token 命令选项。您仅被允许移除您在 GitHub 中拥有仓库访问权限的角色。

要导入新角色

$ ansible-galaxy role import github_user github_repo

默认情况下，该命令将等待 Galaxy 完成导入过程，并在导入进行时显示结果

Successfully submitted import request 41
Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref=
Retrieving GitHub repo githubuser/ansible-role-repo
Accessing branch: devel
Parsing and validating meta/main.yml
Parsing galaxy_tags
Parsing platforms
Adding dependencies
Parsing and validating README.md
Adding repo tags as role versions
Import completed
Status SUCCESS : warnings=0 errors=0

有关其他命令选项，请参阅 ansible-galaxy。

删除角色

delete 命令要求您使用 API 令牌进行身份验证。您可以将其包含在 ansible.cfg 文件中，或使用 --token 命令选项。您仅被允许移除您在 GitHub 中拥有仓库访问权限的角色。

使用以下命令删除角色

$ ansible-galaxy role delete github_user github_repo

这仅将角色从 Galaxy 中移除。它不会移除或更改实际的 GitHub 仓库。

Travis 集成

您可以创建 Galaxy 中的角色与 Travis 之间的集成或连接。一旦建立连接，Travis 中的构建将自动触发 Galaxy 的导入，使用关于角色的最新信息更新搜索索引。

您可以使用 setup 命令及您的 API 令牌来创建集成。您还需要一个 Travis 账户和您的 Travis 令牌。准备就绪后，请使用以下命令创建集成

$ ansible-galaxy role setup travis github_user github_repo xxx-travis-token-xxx

setup 命令需要您的 Travis 令牌，但该令牌不会存储在 Galaxy 中。它与 GitHub 用户名和仓库一起用于创建哈希值，详见 Travis 文档。哈希值存储在 Galaxy 中，用于验证从 Travis 接收到的通知。

setup 命令使 Galaxy 能够响应通知。要配置 Travis 在您的仓库上运行构建并发送通知，请参考 Travis 入门指南。

要指示 Travis 在构建完成后通知 Galaxy，请在 .travis.yml 文件中添加以下内容

notifications:
    webhooks: https://galaxy.ansible.com/api/v1/notifications/

列出 Travis 集成

使用 --list 选项来显示您的 Travis 集成

$ ansible-galaxy role setup --list travis github_user github_repo xxx-travis-token-xxx


ID         Source     Repo
---------- ---------- ----------
2          travis     github_user/github_repo
1          travis     github_user/github_repo

移除 Travis 集成

使用 --remove 选项来禁用并移除 Travis 集成

$ ansible-galaxy role setup --remove ID

提供要禁用的集成 ID。您可以通过使用 --list 选项来查找该 ID。

另请参阅

使用 Ansible 集合

可共享的模块、剧本和角色集合

角色 (Roles)

关于 Ansible 角色的全部内容

交流方式

有疑问？需要帮助？想分享你的想法？请访问 Ansible 通信指南