使用我自己在 git 仓库中托管的 Ansible Collection

2 年 ago
宇, 华
3 minutes

在搭建服务器时，将常见的设置任务等通过 Ansible Collection 进行复用是很方便的。因此，我会记录下参考官方文档进行实际尝试（以及遇到的困难）的步骤。

建立收藏品

在中文中，可以使用 ansible-galaxy collection init 命令创建一个空的集合（骨架）。这里我们将尝试在命名空间 thisis 下创建一个名为 example 的角色。

% ansible-galaxy collection init thisis.example
- Collection thisis.example was created successfully
% find .
.
./thisis
./thisis/example
./thisis/example/plugins
./thisis/example/plugins/README.md
./thisis/example/roles
./thisis/example/docs
./thisis/example/README.md
./thisis/example/galaxy.yml

只需正确的目录结构和galaxy.yml文件，就可以创建集合。

galaxy.yml文件中包含集合的元数据信息。

在执行ansible-galaxy init collection后，会设置默认值如下。

% grep '^[^#]' thisis/example/galaxy.yml
namespace: thisis
name: example
version: 1.0.0
readme: README.md
authors:
- your name <example@domain.com>
description: your collection description
license:
- GPL-2.0-or-later
license_file: ''
tags: []
dependencies: {}
repository: http://example.com/repository
documentation: http://docs.example.com
homepage: http://example.com
issues: http://example.com/issue/tracker
build_ignore: []

只需要一个选项，原文如下：

由于上述必要配置选项仅在 “authors” 之上，因此将收集所需信息并进行相应的编辑。
一旦 “galaxy.yml” 准备好了，就可以在 “roles/” 目录下准备共享的任务等。

% mkdir -p thisis/example/roles/aaa/tasks/
% echo <<EOL > thisis/example/roles/aaa/tasks/main.yml
heredoc> ---
heredoc> - name: aaa
heredoc>   debug:
heredoc>     msg: 問題なし！OK！
heredoc>
heredoc> EOL

如果能做到这一点，之后将 example 文件夹作为一个合适的 git 仓库进行推送，就完成了创建。

尝试使用收藏功能

在要使用 collection 的 playbook 的 requirements.yml 中，指定要使用的 collection（即之前创建的那个）。
如果需要对 Git 仓库进行 SSH 认证，请以 git+ssh://git@~ 的形式指定名称。

% cat requirements.yml
collections:
  - name: git+ssh://git@your-git-host.com/your-org/ansible-collection-example.git
    type: git
    version: main

当你准备好上述内容后，在主机上运行 ansible-galaxy install -r requirements.yml，角色将被安装在主机的 ANSIBLE_COLLECTIONS_PATHS （默认为 ~/.ansible/collections/ 目录）中。

% ansible-galaxy install -r requirements.yml
Starting galaxy collection install process
Process install dependency map
Cloning into '/Users/whoami/.ansible/tmp/(略)/ansible-collection-examplexxxxxx'...
remote: Enumerating objects: 24, done.
remote: Counting objects: 100% (11/11), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 24 (delta 1), reused 0 (delta 0), pack-reused 13
Receiving objects: 100% (24/24), done.
Resolving deltas: 100% (1/1), done.
Already on 'main'
Your branch is up to date with 'origin/main'.
Starting collection install process
Installing 'thisis.example:1.0.0' to '/Users/whoami/.ansible/collections/ansible_collections/thisis/example'
Created collection for thisis.example:1.0.0 at /Users/whoami/.ansible/collections/ansible_collections/thisis/example
thisis.example:1.0.0 was installed successfully

如果到这一步，你可以使用playbook来指定角色并执行。

% find .
.
./inventory
./playbook.yml
./requirements.yml
% cat playbook.yml
- hosts: all

  roles:
    - thisis.example.aaa

% ansible-playbook -i inventory playbook.yml

PLAY [all] **********************************************************************************************************

TASK [Gathering Facts] **********************************************************************************************
ok: [targethost]

TASK [thisis.example.aaa : aaa] *************************************************************************************
ok: [targethost] => {
    "msg": "問題なし！OK！"
}

PLAY RECAP **********************************************************************************************************
targethost               : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

余談：曾经遇到过困难

根据之前写的内容，要创建一个collection，需要有一个包含galaxy.yml和共享的角色实体的目录结构。如果你愿意，你可以自己准备目录，并只在galaxy.yml中写入必需的参数namespace、name、version、readme和authors，就可以创建collection。（实际上，我最初也是这样试的。）

需要注意的是，在这里，namespace和name使用的字符是有限制的。
可以使用的字符是[a-zA-Z0-9_]，不能使用”-“等字符。（这一点在自动生成的galaxy.yml注释中也有说明）

如果命名空间或名称中包含横杆 – ，那么在运行 “ansible-galaxy install -r requirements.yml” 安装成功后，播放书执行时将出现错误。

(安装成功，但是)

% ansible-galaxy install -r requirements.yml
Starting galaxy collection install process
Process install dependency map
Cloning into '/Users/whoami/.ansible/tmp/(略)/ansible-collection-examplexxxxxx'...
remote: Enumerating objects: 31, done.
remote: Counting objects: 100% (18/18), done.
remote: Compressing objects: 100% (13/13), done.
remote: Total 31 (delta 2), reused 0 (delta 0), pack-reused 13
Receiving objects: 100% (31/31), 4.40 KiB | 1.46 MiB/s, done.
Resolving deltas: 100% (2/2), done.
Already on 'main'
Your branch is up to date with 'origin/main'.
Starting collection install process
Installing 'thisis.ex-am-ple:1.0.0' to '/Users/whoami/.ansible/collections/ansible_collections/thisis/ex-am-ple'
Created collection for thisis.ex-am-ple:1.0.0 at /Users/whoami/.ansible/collections/ansible_collections/thisis/ex-am-ple
thisis.ex-am-ple:1.0.0 was installed successfully

（出现错误（提示找不到角色）的运行时情况）

% cat playbook.yml
- hosts: all

  roles:
    - thisis.ex-am-ple.aaa

% ansible-playbook -i inventory playbook.yml
ERROR! the role 'thisis.ex-am-ple.aaa' was not found in /Users/whoami/tmp/roles:/Users/whoami/.ansible/roles:/Users/whoami/tmp

The error appears to be in '/Users/whoami/tmp/playbook.yml': line 4, column 7, but may
be elsewhere in the file depending on the exact syntax problem.

The offending line appears to be:

  roles:
    - thisis.ex-am-ple.aaa
      ^ here

如果直接接收上述的错误消息“找不到角色”，经过一番调查后发现这会浪费大量时间（有经验之谈）。

如果您仔细阅读了Ansible文档（或者阅读了之前显示的警告信息），您就可以了解到关于这个命名限制的内容。或者您也可以通过首先使用”ansible-galaxy collection init”命令创建一个模板，如果命令本身出现错误，您也能够注意到这个问题。

% ansible-galaxy collection init thisis.ex-am-ple
ERROR! Invalid collection name 'thisis.ex-am-ple', name must be in the format <namespace>.<collection>.
Please make sure namespace and collection name contains characters from [a-zA-Z0-9_] only.

因此，阅读官方信息是非常重要的。大家也要注意。

✖
广告
将在 10 秒后关闭
bannerAds