Ansible「ERROR! couldn't resolve module/action」の修正 — モジュールが見つからない

エラーの内容

Ansible プレイブックを実行すると、次のエラーが発生します：

ERROR! couldn't resolve module/action 'community.general.ufw'. This often indicates a misspelling, missing collection, or incorrect module path.

The error appears to be in '/home/user/playbooks/firewall.yml': line 12, column 7, but may
be elsewhere in the file depending on the exact syntax problem.

または短いバージョン：

ERROR! couldn't resolve module/action 'docker_container'

いずれの場合も、プレイブックは完全に停止し、何も実行されません。

原因

Ansible 2.10 以降、多くのモジュールがコアパッケージから取り出され、独立したコレクションに移行されました。2.9 からアップグレードした場合や古いチュートリアルからプレイブックを取得した場合、呼び出しているモジュールはまだインストールされていないコレクションに含まれている可能性があります。

このエラーの原因として最も多いのは次の3つです：

• モジュールを含むコレクションがインストールされていない（例：community.general、community.docker、amazon.aws）
• community.docker.docker_container のような完全修飾コレクション名（FQCN）ではなく、docker_container のような短いモジュール名を使用している
• Ansible がコレクションをインストールした Python 環境とは異なる環境から実行されている

修正1：不足しているコレクションをインストールする

これは約80%のケースに対応する修正です。まず、モジュールがどのコレクションに属しているかを確認します。Ansible コレクションインデックスを確認するか、ローカルで検索してください：

ansible-doc -l | grep docker_container

次にインストールします：

# 単一のコレクションをインストール
ansible-galaxy collection install community.general

# community.docker は docker_container、docker_image などをカバー
ansible-galaxy collection install community.docker

# AWS モジュール
ansible-galaxy collection install amazon.aws

# 一度に複数インストール
ansible-galaxy collection install community.general community.docker ansible.posix

主なモジュールとコレクションの対応表：

• ufw、timezone、htpasswd、git_config → community.general
• docker_container、docker_image、docker_network → community.docker
• ec2、s3_bucket、rds_instance → amazon.aws
• postgresql_db、postgresql_user → community.postgresql
• mysql_db、mysql_user → community.mysql
• k8s、helm → kubernetes.core

修正2：完全修飾コレクション名（FQCN）を使用する

短いモジュール名は、コレクションをインストールした後でも Ansible 2.10 以降では失敗することがあります。最も確実な方法は、すべての箇所で FQCN に切り替えることです：

# 変更前（短い名前 — Ansible 2.10 以降では不安定）
- name: UFW ファイアウォールを管理
  ufw:
    rule: allow
    port: 22

# 変更後（FQCN — 常に動作する）
- name: UFW ファイアウォールを管理
  community.general.ufw:
    rule: allow
    port: 22

Docker の場合も同様です：

# 変更前
- name: nginx コンテナを起動
  docker_container:
    name: nginx
    image: nginx:latest
    state: started

# 変更後
- name: nginx コンテナを起動
  community.docker.docker_container:
    name: nginx
    image: nginx:latest
    state: started

修正3：繰り返し可能なインストールのために requirements.yml を使用する

チームプロジェクトで作業していますか？全員が正しいコレクションをインストールすることを覚えているとは限りません。依存関係を requirements.yml ファイルに記述してリポジトリにコミットしましょう：

# requirements.yml
collections:
  - name: community.general
    version: ">=8.0.0"
  - name: community.docker
    version: ">=3.0.0"
  - name: amazon.aws
    version: ">=7.0.0"

1つのコマンドですべてをインストールします：

ansible-galaxy collection install -r requirements.yml

これを CI/CD パイプラインの最初のステップとして追加し、プレイブックの実行前に行いましょう。

修正4：Python/Ansible 環境が間違っている

コレクションをインストールしてもまだエラーが出ますか？Ansible が別の Python 環境（コレクションがインストールされていない環境）を参照している可能性があります。

# 実際に実行されている ansible バイナリを確認する
which ansible

# インストール済みコレクションとそのパスを一覧表示する
ansible-galaxy collection list

# virtualenv を使用していますか？先にアクティベートしてから再インストールする
source /path/to/venv/bin/activate
ansible-galaxy collection install community.general

デフォルトでは、コレクションは次のいずれかの場所にインストールされます：

• ~/.ansible/collections/ — ユーザーごと
• /usr/share/ansible/collections/ — システム全体
• ./collections/ — プロジェクトローカル（ansible.cfg で設定した場合）

システム全体にインストールしたい場合は、sudo を追加します：

sudo ansible-galaxy collection install community.general

修正5：モジュール名のタイポを確認する

モジュール名自体がスペルミスの場合、コレクションのインストールは役に立ちません。正確な名前を再確認してください：

# キーワードに一致するモジュールを検索する
ansible-doc -l | grep -i postgres

# 特定のモジュールの完全なドキュメントを表示する
ansible-doc community.postgresql.postgresql_db

修正の確認

実際にプレイブックを実行する前に、まず構文チェックを行いましょう：

ansible-playbook playbook.yml --syntax-check

正常な出力は次のようになります：

playbook: playbook.yml

エラーなし。次に、他の問題を確認するためにドライランを実行します：

ansible-playbook playbook.yml --check

コレクションが正しくインストールされたことを確認します：

ansible-galaxy collection list | grep community.general
# community.general    9.1.0

予防策

• すべてのプレイブックで FQCN を使用する — 明示的で、Ansible のアップグレード後も壊れずに動作する
• すべての Ansible プロジェクトに requirements.yml を保持し、バージョン管理にコミットする
• requirements.yml でコレクションのバージョンを固定する — これにより、アップグレード時のサイレントな破損を簡単に防げる
• CI/CD では、プレイブックの実行前に ansible-galaxy collection install -r requirements.yml を実行する
• 2.9 → 2.10 の境界を越えてアップグレードする場合は、コレクションに移行したモジュールについてプレイブックを監査する