Red Hat Certified Engineer (RHCE) #12 Collection: Galaxy、Automation Hub

#11 Role の作成と使用 では、task と変数、handler を role 単位にまとめて再利用する方法を身につけました。ところが Ansible には role よりも一段上のまとまりがあります。それが collection です。今回の記事では collection とは何か、ansible-galaxy で collection と role をどうダウンロードするのか、そして試験でよく出る requirements.yml の一括インストールの流れを実技視点で整理します。

Collection とは何か #

collection は module と role、plugin を 1 つにまとめた配布単位です。かつては Ansible 本体にすべての module が一緒に入っていましたが、今は本体 (ansible-core) とコンテンツ (collection) が分離されています。firewalld や selinux 関連の module も本体ではなく別の collection に入っていて、必要であればその collection をダウンロードして使います。

collection 1 つには次のコンテンツが入り得ます。

• module。task から直接呼び出す作業単位。例えば ansible.posix collection の firewalld module
• role。task と変数、handler をまとめた再利用単位。#11 で扱ったあの role
• plugin。filter、lookup、connection など Ansible の動作を拡張するコード

collection は普通 community.general、ansible.posix、redhat.rhel_system_roles のように namespace.collection 形式の名前を持ちます。前が namespace (制作主体) で後ろが collection 名です。

FQCN: namespace.collection.module #

collection 時代の核心となるルールが FQCN (Fully Qualified Collection Name) です。module を呼ぶとき、短い名前ではなく namespace.collection.module の全体パスで呼ぶ方式です。

# 短い名前 (推奨しない、曖昧)
- name: firewall 設定
  firewalld:
    service: https
    state: enabled

# FQCN (推奨)
- name: firewall 設定
  ansible.posix.firewalld:
    service: https
    state: enabled

ansible.posix.firewalld は ansible.posix collection の firewalld module という意味です。同じ名前の module が複数の collection にあり得るので、FQCN を使えばどの collection の module なのか曖昧さなく指定されます。試験では FQCN で書く習慣 を推奨します。採点環境の collection 構成に関わらず、意図した module が正確に実行されるからです。

本体にデフォルトで含まれる module (例 copy、template、service) は、実は ansible.builtin namespace に属します。したがって ansible.builtin.copy、ansible.builtin.service のように書くのが正確な FQCN です。短い名前でも動作しますが、FQCN は明示的です。

collection のインストール: ansible-galaxy collection install #

collection は ansible-galaxy collection install コマンドでインストールします。

# 単一 collection のインストール
ansible-galaxy collection install ansible.posix

# 特定バージョンの指定
ansible-galaxy collection install ansible.posix:1.5.4

# インストール済み collection の一覧確認
ansible-galaxy collection list

インストールした collection がどこに入るかが試験で重要です。デフォルトではユーザーホームの ~/.ansible/collections にインストールされますが、プロジェクトの中に隔離しておく方式を推奨します。-p オプションでインストールパスを直接指定します。

# プロジェクトディレクトリの中の collections パスにインストール
ansible-galaxy collection install ansible.posix -p collections

このようにプロジェクトルートの collections ディレクトリにインストールすると、同じディレクトリで playbook を実行するとき Ansible がそのパスを自動で認識します。試験で作業ディレクトリが決まっているなら、この方式が安全です。

requirements.yml で一括インストール #

collection が複数あるとき、コマンドを 1 つずつ打つ代わりに、requirements.yml ファイルに依存関係を書いておいて一度にインストールする方式が標準です。この流れが RHCE 試験の定番タイプ です。問題で特定の collection や role をダウンロードして使えと指示されたら、requirements.yml に書いて一括インストールした後、FQCN で呼び出すパターンを使います。

# collections/requirements.yml
---
collections:
  - name: ansible.posix
  - name: community.general
    version: 6.0.0

このファイルを基準に collection を一括インストールします。

ansible-galaxy collection install -r collections/requirements.yml -p collections

-r は requirements ファイルを読み込むオプションで、-p collections でインストールパスをプロジェクトの中に固定します。試験環境がインターネットに直接届かず、社内リポジトリや Automation Hub を指すように設定されている場合があるので、インストールコマンドが失敗したら source 設定から確認します。

role も requirements でインストール #

requirements.yml は collection だけでなく role も一緒にインストールできます。role と collection を 1 つのファイルに書きますが、それぞれ roles と collections キーの下に置きます。

# roles/requirements.yml
---
roles:
  - name: geerlingguy.nginx
  - src: https://github.com/example/my-role.git
    scm: git
    name: my_role

collections:
  - name: ansible.posix

role は ansible-galaxy role install で、collection は ansible-galaxy collection install でインストールしますが、2 つのコンテンツが混ざった requirements ファイルは ansible-galaxy install で一度に処理できます。

# role のみインストール
ansible-galaxy role install -r roles/requirements.yml -p roles

# role と collection を一度にインストール
ansible-galaxy install -r roles/requirements.yml

role のデフォルトインストールパスは ~/.ansible/roles で、-p roles でプロジェクトの中の roles ディレクトリに隔離できます。

Galaxy vs Automation Hub #

collection をダウンロードする出どころは大きく 2 か所です。

Ansible Galaxy はコミュニティ collection が集まる公開リポジトリです。community.general のような collection はここで配布されます。一方 Automation Hub は Red Hat が品質とサポートを保証する認証コンテンツを提供するリポジトリです。企業がサポートを受ける安定した collection を使うには、Automation Hub を出どころに設定します。

どの出どころを使うかは ansible.cfg の [galaxy] セクションで server リストとして指定します。

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy

[galaxy_server.automation_hub]
url = https://console.redhat.com/api/automation-hub/content/published/
auth_url = https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token = <your-token>

[galaxy_server.galaxy]
url = https://galaxy.ansible.com/

server_list に書いた順番で出どころを探索します。試験では出どころがあらかじめ設定されている場合が多いので、新しく構成するよりも、与えられた設定を読んでそのまま活用する方が速いです。

collections_path と ansible.cfg #

インストールした collection を Ansible がどこで探すかは、ansible.cfg の collections_path 設定が決めます (過去の名前は collections_paths で、どちらも認識されます)。

# ansible.cfg
[defaults]
inventory = inventory
collections_path = ./collections:~/.ansible/collections

コロン (:) で複数のパスを区切り、前のパスから優先して探索します。上の設定はプロジェクトの中の collections を先に探し、なければユーザーホームを見ます。1 つ便利な点があって、プロジェクトディレクトリのすぐ下に collections ディレクトリがあれば、collections_path をわざわざ指定しなくても Ansible が自動で認識します。だから -p collections でダウンロードする慣例が試験で安全な選択です。

role の探索パスは別に roles_path が担当します。

[defaults]
roles_path = ./roles:~/.ansible/roles

例題: requirements でインストール後 FQCN で使用 #

collection をダウンロードして FQCN で呼び出す全体の流れを一度に見ます。まずプロジェクト構造です。

project/
├── ansible.cfg
├── inventory
├── collections/
│   └── requirements.yml
└── site.yml

ansible.cfg で作業ディレクトリを整えます。

# ansible.cfg
[defaults]
inventory = inventory
collections_path = ./collections
remote_user = devops

[privilege_escalation]
become = true

インストールする collection を requirements.yml に書き、一括インストールした後に結果を確認します。

# collections/requirements.yml
---
collections:
  - name: ansible.posix

ansible-galaxy collection install -r collections/requirements.yml -p collections
ansible-galaxy collection list | grep ansible.posix

これで playbook で FQCN で module を呼び出します。

# site.yml
---
- name: web server のファイアウォール構成
  hosts: webservers
  tasks:
    - name: httpd のインストール
      ansible.builtin.dnf:
        name: httpd
        state: present

    - name: httpd サービスの有効化
      ansible.builtin.service:
        name: httpd
        state: started
        enabled: true

    - name: https サービスのファイアウォール許可
      ansible.posix.firewalld:
        service: https
        permanent: true
        immediate: true
        state: enabled

playbook を実行します。

ansible-navigator run site.yml -m stdout
# または
ansible-playbook site.yml

ansible.posix.firewalld が別の collection の module なので、事前に collection をインストールしないと module が見つからないというエラーが出ます。したがって インストールが先、使用が後 という順番が採点で点数を分けます。

試験のポイント #

• FQCN で書きます。 module は namespace.collection.module 形式で呼びます。例えば ansible.posix.firewalld、ansible.builtin.copy と書きます。短い名前は曖昧なので、試験では FQCN を推奨します。
• requirements.yml で一括インストールします。 複数の collection や role が必要なら collections/requirements.yml に書いて ansible-galaxy collection install -r ... -p collections で一度にダウンロードします。この流れが試験の定番です。
• インストールパスをプロジェクトの中に固定します。 -p collections でダウンロードすると、同じディレクトリで playbook を実行するとき自動で認識されます。role は -p roles で隔離します。
• collections_path を確認します。 ansible.cfg の collections_path と roles_path がどのパスを見るか確認し、インストールパスと合わせます。
• インストールが先、使用が後。 collection をダウンロードする前に FQCN を呼び出すと module が見つかりません。playbook 実行前にインストールを完了します。
• 出どころ設定をそのまま活用します。 Galaxy と Automation Hub の出どころがあらかじめ構成されている場合、新しく作るよりも ansible.cfg の [galaxy] 設定を読んで活用する方が速いです。

まとめ #

この記事で押さえたこと:

• collection は module と role、plugin をまとめた配布単位 であり、本体 (ansible-core) とコンテンツが分離されています。
• FQCN (namespace.collection.module) で module を呼び出すと曖昧さがありません。試験では FQCN を推奨します。
• ansible-galaxy collection install でインストールし、-r requirements.yml で一括インストールして -p collections でパスを固定します。
• requirements.yml は collection と role を一緒に書けて、ansible-galaxy install で一度に処理できます。
• Galaxy はコミュニティの公開リポジトリ、Automation Hub は Red Hat の認証コンテンツリポジトリ です。
• 探索パスは ansible.cfg の collections_path と roles_path が決めます。

次へ: system roles #

collection で外部コンテンツを取り込む方法を身につけました。ここから Red Hat が RHEL システム管理用に直接提供する認証 role のまとまりである rhel-system-roles に入ります。

#13 system roles (rhel-system-roles) では、redhat.rhel_system_roles collection のインストール、timesync と firewall、selinux のような代表的な role の変数構造、そして試験でよく出る「system role でこの設定を適用せよ」というタイプまで、直接書きながら整理します。