Ansible でタスクを実行している最中に、突然「UNREACHABLE!」や「FAILED!」というエラーメッセージが表示されて困ったことはありませんか。

これらのエラーは、Ansible を使用する際に最も頻繁に遭遇するトラブルです。しかし、適切な手順で診断を行えば、わずか 3 分程度で根本原因を特定し、迅速に解決できます。

本記事では、UNREACHABLE!と FAILED!エラーの効率的な切り分け方法と、実際の現場で使える診断テクニックをご紹介します。エラーの種類別に具体的な対処法を解説し、トラブルシュートの時間を大幅に短縮できる実践的なノウハウをお伝えします。

UNREACHABLE! エラーの切り分け

UNREACHABLE!エラーは、Ansible がターゲットホストに接続できない場合に発生します。このエラーが表示されたら、まずは接続の問題であることを理解し、段階的に原因を特定していきましょう。

以下の図は、UNREACHABLE!エラーの主要な原因とその関係性を示しています。

mermaidCopy codeflowchart TD
    start[UNREACHABLE!エラー発生] --> network{ネットワーク接続}
    network -->|OK| ssh{認証問題}
    network -->|NG| network_fix[ネットワーク設定確認]
    ssh -->|OK| port{ポート・ファイアウォール}
    ssh -->|NG| auth_fix[SSH認証修正]
    port -->|OK| other[その他の原因]
    port -->|NG| port_fix[ポート設定修正]

この図は接続問題の診断フローを表しており、ネットワーク接続から順番に確認することで効率的に原因を特定できます。

ネットワーク接続の確認

最初に確認すべきは、基本的なネットワーク接続です。ping コマンドを使用して、ターゲットホストへの到達性を確認しましょう。

bashCopy code# ターゲットホストへの基本的な接続確認
ping -c 3 target-server.example.com

上記のコマンドで応答がない場合は、以下の原因が考えられます。

原因	確認方法	解決策
DNS の名前解決	nslookup target-server.example.com	​/​etc​/​hostsまたは DNS 設定の修正
IP アドレスの誤り	インベントリファイルの確認	正しい IP アドレスへの修正
ルーティング	traceroute target-server.example.com	ネットワーク経路の見直し

ネットワーク接続が確認できたら、次のステップに進みます。

SSH 認証の問題

ネットワーク接続に問題がない場合、SSH 認証の設定を確認します。Ansible は通常 SSH 接続を使用するため、認証情報が正しく設定されているかが重要です。

bashCopy code# SSH接続の手動テスト
ssh -v username@target-server.example.com

認証に関する詳細な情報を取得するために、verbose オプション（-v）を使用します。

bashCopy code# Ansibleでの詳細なSSH情報確認
ansible target-server -m ping -vvv

よくある認証エラーとその対処法は以下の通りです。

エラー内容	原因	解決策
Permission denied (publickey)	公開鍵認証の失敗	~​/​.ssh​/​authorized_keysの確認・修正
Host key verification failed	ホストキーの不一致	ssh-keyscanでホストキーを更新
Connection refused	SSH Daemon の停止	ターゲットホストで SSH サービスの再起動

SSH 認証の設定例を以下に示します。

yamlCopy code# ansible.cfg での SSH設定例
[defaults]
host_key_checking = False
remote_user = ansible
private_key_file = ~/.ssh/id_rsa

[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s

ポート・ファイアウォールの確認

SSH 認証が正常でも接続できない場合は、ポートやファイアウォールの設定を確認する必要があります。

bashCopy code# ポートの開放状況確認
telnet target-server.example.com 22

# nmap を使用したポートスキャン
nmap -p 22 target-server.example.com

ファイアウォールの確認手順は以下の通りです。

bashCopy code# ローカルホスト側のファイアウォール確認
sudo iptables -L

# ターゲットホスト側の確認（接続後）
sudo ufw status
sudo firewall-cmd --list-all

ポートとファイアウォールに関する主な確認ポイントです。

• SSH ポート: デフォルトは 22 番、カスタムポートの場合はインベントリで指定
• ファイアウォール: 送信元 IP アドレスからのアクセスが許可されているか
• SELinux: 有効な場合は適切なポリシーが設定されているか

FAILED! エラーの切り分け

FAILED!エラーは、ターゲットホストへの接続は成功したものの、実行されたタスクが失敗した場合に発生します。このエラーは実行権限やモジュール固有の問題、設定ファイルの問題など、様々な原因が考えられます。

以下の図は、FAILED!エラーの主な原因と診断の流れを示しています。

mermaidCopy codeflowchart TD
    failed_start[FAILED!エラー発生] --> permission{実行権限チェック}
    permission -->|OK| module{モジュール固有エラー}
    permission -->|NG| permission_fix[権限設定修正]
    module -->|OK| config{設定ファイル確認}
    module -->|NG| module_fix[モジュール設定修正]
    config -->|OK| other_issue[その他の問題]
    config -->|NG| config_fix[設定ファイル修正]

この図は、FAILED!エラーを段階的に診断し、原因を特定する手順を表しています。

タスク実行権限の問題

FAILED!エラーでまず確認すべきは、実行しようとしているタスクに必要な権限があるかどうかです。

bashCopy code# Ansibleでsudo権限が必要なタスクの確認
ansible target-server -m shell -a "sudo whoami" --ask-become-pass

実行権限に関する一般的な問題と解決策は以下の通りです。

問題	症状	解決策
sudo 権限なし	sudo: command not found	sudoers ファイルへの追加
パスワード認証	sudo: a password is required	--ask-become-passオプション使用
ファイル権限	Permission denied	chmodコマンドで権限変更

playbook での権限設定例を以下に示します。

yamlCopy code# 権限昇格を使用するタスクの例
- name: Install package with sudo
  yum:
    name: httpd
    state: present
  become: yes
  become_method: sudo

モジュール固有のエラー

権限に問題がない場合、使用している Ansible モジュール固有のエラーが発生している可能性があります。

bashCopy code# 詳細なエラー情報を取得
ansible-playbook playbook.yml -vvv

よく発生するモジュール固有のエラーとその対処法です。

yamlCopy code# yum モジュールのエラー例と対処
- name: Install package
  yum:
    name: '{{ package_name }}'
    state: present
  register: yum_result
  failed_when: false

- name: Debug yum result
  debug:
    var: yum_result

モジュール別の主なエラーパターンは以下の通りです。

モジュール	一般的なエラー	対処法
yum/apt	Package not found	リポジトリの確認、パッケージ名の検証
file	Path does not exist	パスの存在確認、事前ディレクトリ作成
service	Service not found	サービス名の確認、systemd 設定の確認

設定ファイルの問題

モジュール固有の問題でもない場合は、設定ファイルや変数の問題を確認します。

yamlCopy code# 変数の確認とデバッグ
- name: Debug variables
  debug:
    msg: 'Variable value is: {{ my_variable }}'

- name: Check file existence
  stat:
    path: '{{ config_file_path }}'
  register: file_stat

- name: Debug file status
  debug:
    var: file_stat

設定ファイルに関する主な確認ポイントです。

bashCopy code# 設定ファイルの構文チェック
ansible-playbook --syntax-check playbook.yml

# 変数の展開確認
ansible-playbook --list-hosts playbook.yml
ansible-playbook --list-tasks playbook.yml

よくある設定ファイルの問題と解決策は以下の通りです。

• YAML 構文エラー: インデントやクォートの確認
• 変数の未定義: group_varsやhost_varsでの変数定義確認
• ファイルパス: 絶対パスと相対パスの使い分け確認

高速診断フローチャート

これまでに説明した診断手順を、実際の現場で 3 分以内に実行できるフローチャートとしてまとめます。

3 分で完了する診断手順

以下の図は、UNREACHABLE!と FAILED!エラーを 3 分で診断するための統合フローチャートです。

mermaidCopy codeflowchart TD
    start[エラー発生] --> error_type{エラータイプ}
    error_type -->|UNREACHABLE!| network_check[1分目: pingテスト]
    error_type -->|FAILED!| permission_check[1分目: 権限確認]

    network_check --> ssh_check[2分目: SSH接続テスト]
    ssh_check --> port_check[3分目: ポート・ファイアウォール]

    permission_check --> module_check[2分目: モジュールエラー]
    module_check --> config_check[3分目: 設定ファイル]

    port_check --> solution[解決方法の実施]
    config_check --> solution

この図は、エラータイプに応じて効率的に診断を進める手順を示しており、各段階で 1 分ずつ時間を区切って診断を行います。

実際の診断で使用する 3 分間のチェックリストです。

時間	UNREACHABLE!の場合	FAILED!の場合
1 分目	ping target-host	ansible target -m shell -a "whoami"
2 分目	ssh -v user@target-host	ansible-playbook playbook.yml -vvv
3 分目	nmap -p 22 target-host	ansible-playbook --syntax-check playbook.yml

よくある原因と対処法

現場でよく遭遇するエラーパターンと、それぞれの迅速な対処法をまとめます。

UNREACHABLE!の主なパターン

bashCopy code# パターン1: DNS名前解決エラー
# エラー: "Name or service not known"
# 対処法:
echo "192.168.1.100 target-server" | sudo tee -a /etc/hosts

# パターン2: SSH鍵認証エラー
# エラー: "Permission denied (publickey)"
# 対処法:
ssh-copy-id user@target-server

# パターン3: ポート接続エラー
# エラー: "Connection refused"
# 対処法:
sudo systemctl start sshd

FAILED!の主なパターン

yamlCopy code# パターン1: 権限エラー
# エラー: "Permission denied"
# 対処法:
- name: Task with privilege escalation
  command: systemctl restart httpd
  become: yes

# パターン2: モジュール依存エラー
# エラー: "No package matching 'package_name' found"
# 対処法:
- name: Update package cache first
  yum:
    update_cache: yes
  when: ansible_os_family == "RedHat"

# パターン3: 変数未定義エラー
# エラー: "variable 'undefined_var' is undefined"
# 対処法:
- name: Set default value
  set_fact:
    undefined_var: 'default_value'
  when: undefined_var is not defined

緊急時に使える診断コマンド集です。

bashCopy code# オールインワン診断コマンド
ansible all -m ping -vvv --ask-pass --ask-become-pass

# 詳細なシステム情報取得
ansible target-server -m setup | grep ansible_

# ファイアウォール状態の一括確認
ansible all -m shell -a "sudo iptables -L | head -10" --ask-become-pass

これらのコマンドは、トラブルシューティングの際に即座に問題の全体像を把握するのに役立ちます。

まとめ

本記事では、Ansible の UNREACHABLE!と FAILED!エラーを 3 分で効率的に診断する方法をご紹介しました。

UNREACHABLE!エラーの診断手順は、ネットワーク接続、SSH 認証、ポート・ファイアウォールの順番で確認することが重要です。この順序に従うことで、接続の問題を段階的に切り分けることができます。

FAILED!エラーの診断手順では、実行権限、モジュール固有のエラー、設定ファイルの問題の順で確認を行います。verbose オプションを活用することで、詳細なエラー情報を素早く取得できることも覚えておきましょう。

3 分診断フローチャートを活用すれば、現場での緊急対応時にも冷静に問題を特定できます。各段階で 1 分ずつ時間を区切って診断を行うことで、効率的なトラブルシューティングが可能になります。

トラブルシューティングのコツは、慌てずに段階的に確認を進めることです。今回ご紹介した手順とコマンドを参考に、Ansible でのトラブル対応時間を大幅に短縮していただければと思います。

関連リンク

• Ansible 公式ドキュメント
• Ansible Configuration Settings
• SSH Configuration for Ansible
• Ansible Debugging Guide