謎：インストールしたはずなのに見つからない
手順通りに進めました。requirements.yml ファイルを作成し、依存関係をリストアップして、インストールを実行しました。ターミナルの出力には、ロールのダウンロードが成功したことを示す満足のいく緑色のテキストが表示されたはずです。しかし、プレイブックを実行した途端、Ansibleはイライラさせるような赤いテキストの壁を表示します：
ERROR! the role 'geerlingguy.nginx' was not found in /etc/ansible/roles:/root/.ansible/roles:/usr/share/ansible/roles
まるでAnsibleがあなたの努力を完全に無視しているかのように感じられます。この問題は通常、インストールの失敗ではありません。むしろ、ほとんどの場合、単純なコミュニケーションの行き違いが原因です：ansible-galaxy はロールをあるフォルダに置きましたが、ansible-playbook は全く別の場所を探しているのです。
検索パスのデバッグ方法
まず、そのエラーメッセージに表示されている「Search Path（検索パス）」を確認することから始めましょう。上記の例では、Ansibleは正確に3つのシステム上の場所をチェックしました。もしロールがこれら3つの場所のいずれにもない場合、プレイブックは毎回失敗します。
標準ユーザーとしてインストールした場合、ロールは多くの場合 ~/.ansible/roles に配置されます。しかし、sudo を使ってプレイブックを実行すると、Ansibleは検索先をルートユーザーのホームディレクトリに切り替えます。この不一致は、ローカル開発環境における「ロールが見つからない」エラーの原因の約80%を占めています。逆に、プロジェクト内にローカルにロールをインストールしたものの、設定を更新していない場合、Ansibleはそこを探すべきであることを認識しません。
Ansibleが実際に認識しているものを再確認する
どのロールがアクティブで、ディスク上のどこにあるかを確認するには、次のコマンドを実行します：
ansible-galaxy role list
リストに geerlingguy.nginx は表示されていますか？もし見当たらない、あるいはパスが間違っているように見えるなら、根本原因を特定できたことになります。
ステップバイステップの解決策
方法1：ロールをプロジェクトフォルダに強制的に入れる
依存関係はプロジェクトフォルダ内に保持しましょう。これは、共同作業環境を管理する上で最も信頼できる方法です。グローバルなシステムパスに頼るのではなく、Galaxyにすべてをローカルの roles/ ディレクトリにドロップするように指示します。
ansible-galaxy install -r requirements.yml -p ./roles
ここでは -p（または --roles-path）フラグが非常に役立ちます。これにより、ロールはほとんどのプレイブックが想定している場所、つまりYAMLファイルのすぐ隣にあるサブディレクトリに確実に配置されます。
方法2：ansible.cfgを微調整する
複数のプロジェクトで共有フォルダを使用したい場合もあるでしょう。その場合は、Ansibleにそのフォルダの場所を教える必要があります。プロジェクトのルートに ansible.cfg ファイルを作成または編集し、以下の行を追加します：
[defaults]
roles_path = ./roles:~/.ansible/roles:/usr/share/ansible/roles
この設定により優先順位リストが作成されます。Ansibleはまずプロジェクトのローカルフォルダをチェックし、次にユーザーのホーム、最後にシステム全体のパスをチェックします。これは多くの場合、エラーを完全に解決するための「ミッシングリンク（欠けていた鎖）」となります。
方法3：名前の不一致に注意する
requirements.yml 内の構文エラーも、この頭の痛い問題の原因となります。ロールにカスタム名を割り当てた場合は、元のソース名ではなく、その特定の名前をプレイブックで使用する必要があります。
混乱を招きやすい設定例：
# requirements.yml
- src: geerlingguy.nginx
name: my_custom_nginx
この場合、roles: [geerlingguy.nginx] を呼び出すとクラッシュします。代わりに roles: [my_custom_nginx] を使用する必要があります。
修正の確認
修正を適用したら、パスが一致していることを確認します。もう一度リストコマンドを実行してください：
ansible-galaxy list
出力にプロジェクトの roles ディレクトリが表示されるはずです。最終的な整合性チェックとして、構文フラグを付けてプレイブックを実行し、すべての依存関係が解決されていることを確認します：
ansible-playbook site.yml --syntax-check
エラーなく終了すれば、デプロイの準備は完了です。
プロのヒントとベストプラクティス
これらの問題を未然に防ぐために、常に ansible.cfg ファイルをGitリポジトリにコミットするようにしましょう。これにより、チームのすべての開発者が自動的に同じ検索パスを使用することになり、「自分のマシンでは動くのに」という典型的な言い争いを防ぐことができます。
制限されたネットワークやエアギャップ環境（オフライン環境）を扱う場合、ロールをtarボールとして手動で移動する必要があるかもしれません。これらの転送中にファイルが破損しやすくなります。ロールパッケージを展開する前に、Hash Generator を使用してSHA-256チェックサムを確認することをお勧めします。これは、壊れたインストールのデバッグに何時間も費やすのを防ぐ、わずか30秒のステップです。
学んだ教訓
- **パスは厄介：** `ansible-galaxy` と `ansible-playbook` は、特に `sudo` が関わる場合に、常に同じデフォルトフォルダを共有するとは限りません。
- **ローカルが最適：** `./roles` にロールを保存することで、自動化のポータビリティ（移植性）と予測可能性が高まります。
- **設定が鍵：** `ansible.cfg` を使用して `roles_path` を明示的に定義し、推測に頼るのをやめましょう。