跳到内容

社区用户指南

API

如果您正在寻找 v3 API 参考，请转到 API v3

服务器

我们有多个 beta 站点实例在运行，以涵盖开发、暂存和生产生命周期。

  1. https://beta-galaxy.ansible.com/
  2. https://beta-galaxy-stage.ansible.com/
  3. https://beta-galaxy-dev.ansible.com/

“dev” 实例是从 https://github.com/ansible/galaxy_ng 的 master 分支的新提交自动部署的。暂存和生产部署是通过手动或 git 存储库上的新标签触发的。

所有实例都已连接到 github 社会身份验证，因此您可以使用 github 帐户登录到任何实例。

登录

在任何现代 Web 浏览器中访问 https://beta-galaxy.ansible.com/。站点加载后，单击页面右上角的“登录”链接。在您第一次尝试时，您将被带到 github 授权页面。这是意料之中的，因为 github 社会身份验证是 https://galaxy.ansible.com 和未来替代的默认和唯一支持的登录机制。授权后，您应该被重定向回主页，并在页面右上角看到您的 github 用户名替换了“登录”字样。

生成 API 令牌

用于检索 api 令牌的 GalaxyNG UI 路径与 Galaxy 不同。在左侧导航菜单中，单击“集合”>“Api 令牌管理”。单击蓝色的“加载令牌”按钮以显示您的 API 令牌。

信息

每次单击“加载令牌”时，它都会使旧令牌失效并创建一个新令牌。请务必将您的令牌保存在安全的地方，而不要依赖令牌管理页面来跟踪它。

Ansible Core CLI 设置

默认情况下，ansible-galaxy cli 配置为与 https://galaxy.ansible.com 通信。要配置 ansible core 与 beta galaxy_ng 服务器通信，请创建一个包含以下内容的 ansible.cfg 文件。

[galaxy]
server_list = beta

[galaxy_server.beta]
url = https://beta-galaxy.ansible.com/api/
token = <your-api-token>

重要

如果您计划导入或上传内容，则只需要在配置中设置令牌。完全支持匿名只读操作。

查找角色

可以通过 UI、api 或 galaxy cli 搜索独立角色。

UI

在左侧导航菜单中，单击“旧版”，然后单击“旧版角色”。旧版角色页面加载后，页面顶部将显示一个筛选工具。搜索选项是关键字或标签。标签来自角色的元数据文件，由角色作者定义。关键字是对角色命名空间、名称和描述的全文搜索。

API

v1 rest api 具有与 https://galaxy.ansible.com 上的当前代码类似的筛选器参数支持。

# Find all roles created by a specific github user.
curl 'https://beta-galaxy.ansible.com/api/v1/roles/?github_user=geerlingguy'

# Find all roles containing a keyword in the namespace, name or description.
curl 'https://beta-galaxy.ansible.com/api/v1/roles/?keyword=docker'

CLI

ansible-galaxy CLI 也支持角色搜索

ansible-galaxy role search --help

查找集合

集合在 UI 中确实具有搜索支持。

  1. 在左侧导航中单击“集合”。
  2. 选择关键字或标签。
  3. 键入术语或选择一个标签来筛选结果列表。

ansible-galaxy CLI 中未来对集合搜索的支持待定。

安装角色

角色安装应该像以前使用 https://galaxy.ansible.com 一样工作

ansible-galaxy role install geerlingguy.docker

安装集合

集合安装应该像以前使用 https://galaxy.ansible.com 一样工作

ansible-galaxy collection install community.general

导入角色

仅通过 ansible galaxy cli 支持角色导入。设置有效的 ansible.cfg 后，运行 ansible-galaxy role import 命令以导入您托管在 https://github.com 上的角色之一

ansible-galaxy role import <github_user> <github_repo>

角色版本

角色版本源自符合语义版本标准的 git 标签。在导入过程中，后端会查找任何与 semver 兼容（删除了前面的 v 或 V）的 git 标签，并将它们添加为角色版本。

更新角色

通过重新导入角色来“更新”角色。

ansible-galaxy role import <github_user> <github_repo>

删除角色

可以通过 ansible-galaxy CLI 或任何 http 客户端（例如 curl）删除角色。

ansible-galaxy CLI

ansible-galaxy role delete <github_user> <github_repo>

http 客户端

首先，找到您要删除的确切角色 ID。

curl https://galaxy.ansible.com/api/v1/roles/?owner__username=<命名空间名称>&name=<角色名称>

现在通过其完整 URL 向该角色发出 DELETE 调用。

curl -X DELETE -H 'Authorization: token <令牌>' https://galaxy.ansible.com/api/v1/roles/<角色 ID>/

更改角色

每个角色都有一个唯一的标识符，我们称之为“完全限定名称”，简称 FQN。如果更改了角色的名称或命名空间名称，则以前 FQN 的安装将失败。

在许多情况下，FQN 与 github_user 和 github_repo 匹配，但也有许多例外情况。例如，许多角色托管在名为 ansible-role-<角色名称> 的 github 存储库中。在导入时，后端服务器将自动修剪 ansible-role- 前缀以创建角色的真实名称。还有一些情况是管理员在旧 galaxy 中为用户创建了一个自定义命名空间，然后通过 UI 将角色导入到该特定命名空间中，因为 CLI 将无法处理它。还有一些情况是 github_user 或 github_repo 在 github 上重命名，导致 FQN 不再匹配这些属性。

角色 FQN 与角色来源的 github_user 和 github_repo 不密切相关可能会导致各种问题

  • 命名冲突。
  • 如果用户在不更改角色命名空间和 github_user 的情况下更改其 github 登录名，则旧登录名可能会被任何人回收，并且 galaxy 对角色的所有权完整性会受到损害。
  • 如果除了角色作者之外的其他人当前具有匹配的 github 登录名，则如果他们曾经使用该系统，则该人将被迫在 galaxy 中使用不同的命名空间。
  • 混淆。
  • 如果用户在登录 galaxy 之前，他们的 github 登录名被其他人创建为自定义命名空间，则用户将不知道哪个命名空间是真实的人。
  • 角色用户知道通过 FQN 安装，因为这是在博客文章或其他社交媒体上引用的内容，以及 requirements.yml 中的内容。如果角色命名空间或名称更改，所有这些互联网引用都将不再有效。用户将必须访问 galaxy 并尝试通过搜索找到该角色已重命名为什么。
  • galaxy 的管理员和版主花费大量时间试图找出为什么 github 用户“foo”不拥有命名空间“bar”或为什么“Foo”不拥有“foo”或为什么“jimbob”无法将角色导入“jimB0B”。

更改命名空间名称或 github_user

如果您认为您的角色在不同的命名空间或 github_user 下会更好，这里是建议的路径...

  1. 按 ID 删除角色，因为它们当前存在于 galaxy 上。
  2. 在 github 上创建一个新的用户名。
  3. 将角色的 github 存储库移动到新的 github 用户名。
  4. 使用新的 github 用户名登录到 galaxy。（命名空间将在登录时自动创建）
  5. 为新用户名创建 galaxy API 令牌。
  6. 从新位置重新导入角色。ansible-galaxy role import <new_github_user> <仓库名称>

我们建议选择一个全部小写、以字母开头且不包含连字符的 github 用户名。这确保了相应的集合命名空间（将在其中控制所有权）不需要进行名称转换。

更改 github_repository

  1. 使用 HTTP 客户端按其当前 ID 删除角色。
  2. 将角色的 github 存储库重命名为新名称。
  3. 从新位置重新导入角色。ansible-galaxy role import <github_user> <新存储库名称>

更改角色名称

有两种方法可以实现此目的，两者都涉及重新导入角色。

A. ansible-galaxy role import --role-name=<新名称> <github_user> <github_repo> B. 修改角色的 meta/main.yml 文件中的 name 字段，然后导入 ansible-galaxy role import <github_user> <github_repo>

第二种选择更具可预测性和可靠性。

上传集合

可以通过 ansible galaxy CLI 或 GalaxyNG Web 界面上传集合。

Galaxy CLI

ansible-galaxy collection publish --help

Web 界面

  1. 在左侧导航栏中点击 “Collections”（集合）。
  2. 点击 “Namespace”（命名空间）。
  3. 在中心页面，点击页面中间上方的标签，显示 “My namespaces”（我的命名空间）。
  4. 在列出的其中一个命名空间上点击 “view collections”（查看集合）。
  5. 如果该集合没有之前的版本，点击蓝色的 “Upload Collection”（上传集合）按钮，并按照提示操作。
  6. 如果该集合有之前的版本，点击右上角的垂直三点汉堡菜单，选择 “upload new version”（上传新版本），然后按照提示操作。

删除命名空间

要删除一个命名空间，您必须首先删除与此命名空间关联的任何角色命名空间。

  1. 导航至该命名空间并选择 Role namespaces（角色命名空间）。
  2. 复制 URL。
  3. 使用 curl 删除该角色命名空间。

curl -H 'Authorization: token <yourtoken>' -X DELETE https://galaxy.ansible.com/ui/standalone/namespaces/<number>/
一旦与此命名空间关联的所有角色命名空间被删除，您就可以删除整个命名空间。1. 导航至该命名空间。2. 选择命名空间右侧的三点菜单，并选择 delete namespace（删除命名空间）。