Ansible CollectionsとFQCNの基礎知識｜ansible.builtinと外部コレクション導入の実践手順

この記事のポイント

・FQCNは「名前空間.コレクション名.モジュール名」の3パート形式でAnsible 2.10から標準化された
・ansible.builtinは追加インストール不要の組み込みコレクションでcopy/file/serviceなどが含まれる
・外部CollectionはCollection単位でインストールしrequirements.ymlで宣言管理できる
・ansible-lintのfqcn警告はモジュール名をFQCN形式に書き直すことで解消できる

# FQCNの基本形式
名前空間.コレクション名.モジュール名（またはプラグイン名）

# 具体例その1: 組み込みモジュール
ansible.builtin.copy
^^^^^^^  ^^^^^^^  ^^^^
名前空間  コレクション名  モジュール名

# 具体例その2: コミュニティコレクション
community.general.java_cert
^^^^^^^^^  ^^^^^^^  ^^^^^^^^^
名前空間   コレクション名  モジュール名

# community.generalをインストール（最新版）
ansible-galaxy collection install community.general

# バージョンを指定してインストール
ansible-galaxy collection install community.general:9.5.0

# ansible.posixをインストール
ansible-galaxy collection install ansible.posix

# 実行結果の例（RHEL 10 環境）
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://galaxy.ansible.com/download/community-general-9.5.0.tar.gz
Installing 'community.general:9.5.0' to '/root/.ansible/collections/ansible_collections/community/general'
community.general:9.5.0 was installed successfully

# requirements.yml（Collectionセクション）
---
collections:
  - name: ansible.posix
    version: ">=1.5.0"

  - name: community.general
    version: "9.5.0"

  - name: community.mysql
    version: ">=3.8.0"

# Collectionのみインストール（--type collection は省略可）
ansible-galaxy collection install -r requirements.yml

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

# CollectionとRoleを両方インストールする場合は2コマンドを順に実行する
ansible-galaxy collection install -r requirements.yml
ansible-galaxy role install -r requirements.yml

# ansible.cfg の設定例（プロジェクトルートに配置）
[defaults]
collections_path = ./collections:/usr/share/ansible/collections

# 設定後、パスが正しく読まれているか確認
ansible-config dump | grep COLLECTIONS_PATHS

# 出力例（RHEL 10 / rocky9-admin ユーザーの場合）
COLLECTIONS_PATHS(/home/rocky9-admin/project/ansible.cfg) = ['/home/rocky9-admin/project/collections', '/usr/share/ansible/collections']

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

# 出力例（RHEL 10 環境）
# /root/.ansible/collections/ansible_collections
Collection        Version
----------------- -------
ansible.posix     1.5.4
community.general 9.5.0

# /usr/lib/python3.12/site-packages/ansible_collections
Collection        Version
----------------- -------
amazon.aws        8.2.1
ansible.netcommon 6.1.2

# FQCN直接記述（推奨）
---
- name: Webサーバーセットアップ
  hosts: webservers
  tasks:
    - name: Nginxをインストールする
      ansible.builtin.dnf:
        name: nginx
        state: present

    - name: Nginx設定ファイルをコピーする
      ansible.builtin.copy:
        src: nginx.conf
        dest: /etc/nginx/nginx.conf
        owner: root
        group: root
        mode: '0644'

    - name: Nginxサービスを起動して自動起動を有効にする
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: yes

    - name: sudoersにdeployユーザーを追加する（community.generalのモジュール）
      community.general.sudoers:
        name: deploy-user
        user: deploy
        commands: ALL
        nopassword: yes

# collections:ディレクティブによる短縮記法（参考）
---
- name: コミュニティモジュールをまとめて使うPlay
  hosts: dbservers
  collections:
    - community.general
    - community.mysql

  tasks:
    - name: MySQLデータベースを作成する（FQCN省略形）
      mysql_db:          # community.general.mysql_db を指す
        name: appdb
        state: present

# ansible-lint実行時の警告例
ansible-lint playbook.yml

# 出力例（FQCN未使用の警告）
WARNING  Listing 3 violation(s) that are fatal
playbook.yml:8: fqcn[action-core]: Use FQCN for builtin module actions: copy
playbook.yml:15: fqcn[action-core]: Use FQCN for builtin module actions: service
playbook.yml:22: fqcn[action-core]: Use FQCN for builtin module actions: dnf

# 変更前（短縮名）
- name: 設定ファイルをコピーする
  copy:
    src: app.conf
    dest: /etc/app/app.conf

# 変更後（FQCN）
- name: 設定ファイルをコピーする
  ansible.builtin.copy:
    src: app.conf
    dest: /etc/app/app.conf

# よくあるエラー
ERROR! couldn't resolve module/action 'community.general.sudoers'.
This often indicates a misspelling, missing collection, or incorrect module path.

# 診断手順
# 1. Collection名にタイポがないか確認
ansible-galaxy collection list | grep community.general

# 2. インストールされていない場合はインストール
ansible-galaxy collection install community.general

# 3. ansible.cfgのcollections_pathが正しいか確認
ansible-config dump | grep COLLECTIONS_PATHS

# 4. モジュール名の正式名称をドキュメントで確認
ansible-doc -t module community.general.sudoers

# プロキシを環境変数で指定してインストール
export HTTPS_PROXY=http://proxy.example.com:8080
ansible-galaxy collection install community.general

# または ansible.cfg にGalaxyサーバーの設定を追記
# [galaxy]
# server_list = release_galaxy
# 
# [galaxy_server.release_galaxy]
# url=https://galaxy.ansible.com/
# # proxy=http://proxy.example.com:8080