何が起きているか
プレイブックを実行すると、Ansibleが次のメッセージを表示します：
[WARNING]: Could not match supplied host pattern, ignoring: webservers
[WARNING]: No hosts matched, nothing to do
プレイブックはタスクを1つも実行せずに即座に終了します。Ansibleはインベントリファイルを見つけましたが、プレイブックの hosts: フィールドで参照しているホストグループまたはホスト名を見つけられませんでした。
ほとんどの場合、原因は名前の不一致です。タイポ、誤ったインベントリパス、またはインベントリファイルの構造上の問題です。どこを確認すればよいかわかれば、大抵2分で解決できます。
デバッグ手順
ステップ1 — Ansibleがインベントリで実際に認識しているものを確認する
まずここから始めましょう。Ansibleにインベントリから解析できるすべてのホストとグループを列挙させます：
# 特定のインベントリファイルを使用する場合
ansible-inventory -i inventory.ini --list
# ディレクトリを使用する場合
ansible-inventory -i inventories/production --list
JSONの出力を確認します。webservers（または参照したグループ名）が存在しない場合、Ansibleは本当にそれを見つけられていません。ファイル自体に問題があるか、間違ったファイルを指定しています。
見やすいツリー形式で確認したい場合は --graph を使用します：
ansible-inventory -i inventory.ini --graph
正常なグループの表示はこのようになります：
@all:
|--@webservers:
| |--web01.example.com
| |--web02.example.com
|--@ungrouped:
ステップ2 — プレイブックが参照している内容を確認する
プレイブックを開いて hosts: の行を確認します：
---
- name: Deploy web app
hosts: webservers
tasks:
...
この値は、インベントリ内のグループ名またはホスト名と完全に一致している必要があります。大文字・小文字も区別されます。スペースも不可です。必要であれば1文字ずつ確認してください — 1文字でも違えばこのエラーが発生します。
ステップ3 — 正しいインベントリファイルを指定しているか確認する
最もよくある原因は、-i を指定せずにプレイブックを実行し、Ansibleが暗黙的に /etc/ansible/hosts にフォールバックしてしまうことです。そのファイルは通常空か、自分のグループが含まれていません。
# 誤り — デフォルトの /etc/ansible/hosts を使用してしまう
ansible-playbook deploy.yml
# 正しい — インベントリを明示的に指定する
ansible-playbook -i inventory.ini deploy.yml
ansible-playbook -i inventories/production deploy.yml
毎回 -i を入力する手間を省くには、ansible.cfg にパスを一度設定します：
[defaults]
inventory = ./inventory.ini
解決策
修正1 — インベントリファイルの構造を修正する
[webservers] グループを含む有効なINIインベントリはこのようになります：
[webservers]
web01.example.com
web02.example.com ansible_user=ubuntu
[dbservers]
db01.example.com ansible_user=centos ansible_port=22
グループのマッチングを気づかないうちに壊してしまう4つのミス：
- ブラケット内の余分なスペース：
[ webservers ]— Ansibleはこれを別の文字列として扱い、グループwebserversとは認識されません - タイポ：インベントリでは
[webserver]、プレイブックではhosts: webservers - グループヘッダーより前にホストが記述されている —
[ungrouped]に入ってしまいます - YAMLのインベントリ構文を
.iniファイルに誤って使用している（またはその逆）
YAMLインベントリを使いたい場合は、同等の構造はこのようになります：
all:
children:
webservers:
hosts:
web01.example.com:
web02.example.com:
ansible_user: ubuntu
dbservers:
hosts:
db01.example.com:
ansible_user: centos
修正2 — hostsパターンを正確に一致させる
インベントリに実際に存在するパターンを使うようにプレイブックを修正します：
---
- name: Deploy web app
hosts: webservers # インベントリと完全に一致している必要がある
become: true
tasks:
- name: Install nginx
apt:
name: nginx
state: present
Ansibleでは複数のグループを同時に対象にするためのパターン指定がいくつかあります：
hosts: all # インベントリ内の全ホスト
hosts: webservers,dbservers # 複数グループ
hosts: webservers:&staging # AND条件（webservers かつ staging）
hosts: webservers:!dbservers # webservers から dbservers を除外
修正3 — ansible.cfgにインベントリパスを追加する
プレイブックの隣にプロジェクトレベルの ansible.cfg を置けば、以降 -i を指定する必要はありません：
[defaults]
inventory = ./inventory.ini
remote_user = ubuntu
host_key_checking = False
Ansibleはカレントディレクトリの ansible.cfg を自動的に読み込みます。これにより -i なしで ansible-playbook deploy.yml を実行しても正しく動作するようになります。
確認方法
サーバーに手を加える前に実行しておくべき3つのコマンドです：
# グループが正しく表示されることを確認
ansible-inventory -i inventory.ini --graph
# プレイブックのドライラン（変更は適用されない）
ansible-playbook -i inventory.ini deploy.yml --check
# 対象となるホストを一覧表示する
ansible-playbook -i inventory.ini deploy.yml --list-hosts
--list-hosts が成功した場合の表示はこのようになります：
playbook: deploy.yml
play #1 (webservers): Deploy web app
pattern: ['webservers']
hosts (2):
web01.example.com
web02.example.com
それでもホスト数が0だったり警告が出る場合は、ステップ1に戻ってください。
ヒント
webservers:&production:!disabled のような複雑なパターンは、特にインベントリが大きくなるほど間違えやすいです。プレイブックにパターンを記述する前に、ToolCraftのRegex Tester でロジックを確認しています。ホストリストを貼り付けて、パターンが期待通りにマッチするかテストできます。データはアップロードされず完全にブラウザ上で動作するため、内部サーバー名を含むリストを扱う際も安心です。
教訓
- プロジェクトディレクトリ外から実行する場合は常に
-iを明示的に指定するか、ansible.cfgを設定してインベントリが常に正しく解決されるようにしましょう。 - プレイブックが予期しない動作をするときはまず
ansible-inventory --graphを実行する — 自分が書いたと思っている内容ではなく、Ansibleが実際に解析した内容が表示されます。 - INIのグループヘッダーはホワイトスペースに敏感です — Ansibleにとって
[webservers]と[ webservers ]は別の文字列です。 - 重要な実行前には毎回
--list-hostsを使う — 安全な読み取り専用のチェックで、実際のサーバーにタスクが触れる前にターゲットを確認できます。