Galaxy 开发者指南

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

为 Galaxy 创建集合

集合是 Ansible 内容的一种分发格式。您可以使用集合来打包和分发剧本、角色、模块和插件。您可以通过 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。

强制执行 (Force)

如果当前工作目录中已经存在与角色名称匹配的目录，则 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 通信指南