Ansibleエラーの修正：couldn't resolve module/action 'community.general.docker_container'

このエラーが発生する理由

Ansibleはバージョン2.10からモジュールの扱い方を変更しました。以前のAnsibleは、すべてのモジュールがあらかじめインストールされている「batteries-included（電池付属）」ツールでした。現在は、**コレクション（Collections）**と呼ばれる分散型モデルを採用しています。このエラーが表示される場合、ローカル環境にDockerモジュールを含む特定のパッケージが不足しています。

ERROR! couldn't resolve module/action 'community.general.docker_container' というエラーは、通常、community.general コレクションが検索パス内に存在しないことを意味します。インストールされていないか、Ansibleが間違ったフォルダを参照している可能性があります。

主な原因

コレクションの不足: ansible-galaxy によるインストールコマンドをまだ実行していない。
パスの不一致: コレクションは ~/.ansible/collections にインストールされているが、設定が別の場所を指している。
仮想環境の競合: システムのPythonにコレクションをインストールしたが、プレイブックを venv 内で実行している。
名前空間の変更: 多くのDockerモジュールは community.general に含まれていますが、一部は community.docker に移行されました。

ステップ別の修正方法

1. コレクションを手動でインストールする

最も簡単な解決策は、Ansible Galaxyレジストリから直接コレクションを取得することです。ターミナルを開き、以下のコマンドを実行してください。

ansible-galaxy collection install community.general

Dockerモジュールは頻繁に更新されるため、将来的な解決エラーを避けるために、特定のDockerコレクションもインストールしておくことをお勧めします。

ansible-galaxy collection install community.docker

2. requirements.yml ファイルを使用する

チームプロジェクトで依存関係を手動で管理するのはリスクが伴います。代わりに、プロジェクトのルートにある requirements.yml ファイルを使用してバージョンを管理しましょう。これにより、チーム全員が同じ環境を使用できるようになります。

以下の内容で requirements.yml を作成します。

---
collections:
  - name: community.general
    version: 8.2.0
  - name: community.docker
    version: 3.10.0

-r フラグを使用して、すべてを一度にインストールします。

ansible-galaxy collection install -r requirements.yml

3. コレクションのパスを確認する

ファイルは存在するものの、Ansibleが間違った場所を探している場合があります。デフォルトでは、Ansibleは ~/.ansible/collections と /usr/share/ansible/collections を検索します。現在の設定を確認するには、以下を実行してください。

ansible --version

configured module search path の行を確認してください。コレクションをプロジェクトフォルダ内（例：./collections ディレクトリ）に保持したい場合は、ansible.cfg ファイルを更新します。

[defaults]
collections_path = ./collections:~/.ansible/collections:/usr/share/ansible/collections

4. Python仮想環境への対応

仮想環境（venv）は、しばしばパスの混乱を引き起こします。venvを使用している場合は、その環境がアクティブな状態でコレクションをインストールしてください。よくある罠は、システムの ansible-galaxy バイナリを使用して、venvベースの ansible-playbook 実行用のモジュールをインストールしてしまうことです。

安全を期すために、Pythonモジュールの構文を使用してGalaxyツールを呼び出し、正しい環境にインストールされるようにします。

python3 -m ansible galaxy collection install community.general

修正の確認

Ansibleがモジュールを認識したか確認します。以下のコマンドでインストール済みのコレクションを一覧表示します。

ansible-galaxy collection list

リストに community.general が表示されたら、簡単なアドホックテストを試してください。以下のコマンドを実行して、Ansibleがモジュールのドキュメントを取得できるか確認します。

ansible localhost -m community.general.docker_container --help

エラーの代わりに大量のヘルプテキストが表示されれば、準備完了です。

トラブルシューティングのヒント

FQCNを使用する: 常に完全修飾コレクション名（Fully Qualified Collection Name）を使用してください。単なる docker_container ではなく、community.general.docker_container と記述します。これにより、名前の競合を防ぐことができます。
権限を確認する: sudo を使用してAnsibleをインストールした場合、コレクションをグローバルにインストールするために sudo が必要な場合があります。ただし、権限トラブルを避けるために、ユーザーレベルでインストールすることをお勧めします。
オフライン環境（エアギャップ）: サーバーがインターネットに接続されていない場合は、GalaxyのWebサイトから .tar.gz をダウンロードしてください。その後、ansible-galaxy collection install ./my-collection.tar.gz を使用してローカルにインストールします。