※本ページにはプロモーション(広告)が含まれています

【2026年最新版】AnsibleでSSH接続がタイムアウトする・接続できない原因と対処法【完全ガイド】

Ansibleの「UNREACHABLE」「SSH timeout」エラーとは

Ansible playbook実行時に表示される代表的なSSHエラーを整理します。

TASK [Gathering Facts] ***************************************
fatal: [192.168.1.10]: UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: ssh: connect to host 192.168.1.10 port 22: Connection timed out",
    "unreachable": true
}

このエラーが発生する原因は主に以下のカテゴリに分類できます。

カテゴリ	具体的な原因	確認方法
ネットワーク	ファイアウォール、ルーティング不備	pingやtelnet/ncで疎通確認
SSH設定	ポート番号ミス、鍵認証失敗	手動SSHで接続テスト
タイムアウト設定	接続タイムアウトが短すぎる	ansible.cfgの確認
known_hosts	ホストキーの不一致・未登録	SSHエラーメッセージで確認
インベントリ設定	IPアドレス・ユーザー名の誤り	インベントリファイルを確認
踏み台サーバー	Bastion経由の設定不備	ProxyJump設定の確認

ステップ1: まず手動SSHで接続確認

Ansible以前に、SSH接続自体が成功するかを確認します。これで問題の切り分けができます。

# 手動SSH接続テスト
ssh -v username@192.168.1.10

# 22番以外のポートの場合
ssh -v -p 2222 username@192.168.1.10

# 特定の鍵ファイルを指定
ssh -v -i ~/.ssh/my_key username@192.168.1.10

# タイムアウト値を指定（10秒）
ssh -v -o ConnectTimeout=10 username@192.168.1.10

手動SSHが成功してAnsibleだけ失敗する場合は、ansible.cfgや接続設定の問題です。手動SSHも失敗する場合は、ネットワークまたはSSHサービスの問題です。

ポートの疎通確認

# TCP接続テスト（netcat）
nc -zv 192.168.1.10 22

# telnetでのポート確認
telnet 192.168.1.10 22

# nmap でポートスキャン（疎通できるポートを探す）
nmap -p 22,2222 192.168.1.10

ステップ2: ansible.cfg のタイムアウト設定を最適化

デフォルトのAnsible接続タイムアウトは10秒です。ネットワーク遅延が大きい環境やクラウド環境では不足する場合があります。

ansible.cfg の基本設定

# ansible.cfg
[defaults]
# SSH接続タイムアウト（秒）デフォルト10秒 → 30秒に変更
timeout = 30

# SSH接続の再試行回数
# デフォルト3回
forks = 5

# ログ出力先
log_path = /var/log/ansible.log

# コントロールパスのディレクトリ（SSH多重化用）
control_path_dir = ~/.ansible/cp

# SSH引数の追加設定
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o StrictHostKeyChecking=no -o ConnectTimeout=30

[ssh_connection]
# SSH接続のパイプライン有効化（パフォーマンス向上）
pipelining = True

# SSH接続のタイムアウト
timeout = 30

# 接続リトライ
retries = 3

環境変数での一時的な設定

# 一時的にタイムアウトを延ばしてplaybookを実行
ANSIBLE_TIMEOUT=60 ansible-playbook playbook.yml

# 詳細なSSHデバッグ情報を表示
ANSIBLE_SSH_ARGS="-vvv" ansible-playbook playbook.yml

ステップ3: インベントリファイルのSSH設定を見直す

インベントリファイルでホストごとのSSH設定を詳細に指定できます。

INI形式のインベントリ設定例

# inventory/hosts.ini

[webservers]
# SSH接続に必要な情報をホストごとに指定
web01 ansible_host=192.168.1.10 ansible_port=22 ansible_user=ubuntu ansible_ssh_private_key_file=~/.ssh/web_key

# SSH ポートが22以外の場合
web02 ansible_host=192.168.1.11 ansible_port=2222 ansible_user=ec2-user

[webservers:vars]
# グループ全体のデフォルト設定
ansible_ssh_private_key_file=~/.ssh/id_rsa
ansible_user=ubuntu

[all:vars]
# 全ホストへのSSH共通設定
ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'

YAML形式のインベントリ設定例

# inventory/hosts.yml
all:
  children:
    webservers:
      hosts:
        web01:
          ansible_host: 192.168.1.10
          ansible_user: ubuntu
          ansible_port: 22
          ansible_ssh_private_key_file: ~/.ssh/web_key
        web02:
          ansible_host: 192.168.1.11
          ansible_user: ec2-user
          ansible_port: 2222
      vars:
        ansible_ssh_common_args: "-o StrictHostKeyChecking=no"

ステップ4: known_hostsの問題を解決する

ホストキー不一致エラー

サーバーを再構築した場合などにSSHホストキーが変わり、以下のようなエラーが発生します。

UNREACHABLE! => {
    "msg": "Failed to connect to the host via ssh: @@@@@@@@@@@@@@@@@@@@@@@@@\nWARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!\n..."
}

known_hostsからエントリを削除する

# 特定ホストのエントリを削除
ssh-keygen -R 192.168.1.10

# ホスト名でも削除（両方削除推奨）
ssh-keygen -R web01.example.com

# 再接続して新しいホストキーを登録
ssh username@192.168.1.10

開発環境での一時的な回避（本番環境には非推奨）

# ansible.cfg で StrictHostKeyChecking を無効化（開発環境のみ）
[defaults]
host_key_checking = False

# または ssh_args で指定
ssh_args = -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null

注意: 本番環境でのhost_key_checking無効化はMan-in-the-Middle攻撃のリスクがあります。開発・テスト環境でのみ使用し、本番では適切にknown_hostsを管理してください。

ステップ5: ファイアウォール・セキュリティグループの確認

Linux iptables / firewalldの確認

# iptables の確認
iptables -L INPUT -n -v | grep 22

# firewalld の確認（RHEL/CentOS系）
firewall-cmd --list-all

# SSH ポートを許可する（firewalld）
firewall-cmd --permanent --add-service=ssh
firewall-cmd --reload

# ufw の確認（Ubuntu系）
ufw status
ufw allow 22/tcp

クラウド環境（AWS/Azure/GCP）のセキュリティグループ確認

クラウド環境では、OSのファイアウォール以外にもセキュリティグループやネットワークACLでSSHポートが制限されている場合があります。

• AWS: EC2インスタンスのセキュリティグループ → インバウンドルール → TCP 22 → AnsibleコントロールノードのIPを許可
• Azure: NSG（ネットワークセキュリティグループ）→ 受信セキュリティ規則 → ポート22を確認
• GCP: VPCファイアウォールルール → ssh（tcp:22）を許可

ステップ6: 踏み台（Bastion Host）経由の接続設定

プライベートネットワーク内のサーバーに接続するために、踏み台サーバー（Bastion Host / Jump Host）を経由するケースは多くあります。

インベントリでのProxyJump設定

# inventory/hosts.ini
[private_servers]
# 踏み台経由で接続するプライベートサーバー
private01 ansible_host=10.0.1.10 ansible_user=ubuntu

[private_servers:vars]
# ProxyJump（踏み台）設定
ansible_ssh_common_args='-o ProxyJump=bastion-user@bastion.example.com:22'

# 踏み台の鍵ファイルを指定する場合
# ansible_ssh_common_args='-o ProxyJump="bastion-user@bastion.example.com" -i ~/.ssh/bastion_key'

ansible.cfg での踏み台設定

# ansible.cfg
[ssh_connection]
ssh_args = -o ProxyJump=bastion-user@bastion.example.com -o StrictHostKeyChecking=no -o ControlMaster=auto -o ControlPersist=60s

~/.ssh/config を使った踏み台設定（推奨）

Ansible専用設定よりも、SSH configで管理する方がメンテナンスしやすいです。

# ~/.ssh/config

# 踏み台サーバー
Host bastion
    HostName bastion.example.com
    User bastion-user
    IdentityFile ~/.ssh/bastion_key
    Port 22

# プライベートサーバー（踏み台経由）
Host 10.0.1.*
    User ubuntu
    IdentityFile ~/.ssh/private_key
    ProxyJump bastion
    StrictHostKeyChecking no

この設定をした上でAnsibleを実行すると、自動的に踏み台を経由してSSH接続されます。

SSH Agent Forwarding を使う方法

# SSH Agentに鍵を追加
ssh-add ~/.ssh/private_key

# 踏み台経由でSSH Agent Forwardingを有効にして接続
ssh -A bastion-user@bastion.example.com

# ansible.cfg での設定
[ssh_connection]
ssh_args = -A -o ProxyJump=bastion-user@bastion.example.com

ステップ7: Ansibleのデバッグモードで原因を特定

詳細ログで実行する

# -v: 基本的な詳細情報
ansible-playbook -v playbook.yml

# -vv: さらに詳細
ansible-playbook -vv playbook.yml

# -vvv: SSH接続の詳細なデバッグ情報
ansible-playbook -vvv playbook.yml

# -vvvv: 接続デバッグの最詳細情報
ansible-playbook -vvvv playbook.yml

ansible pingモジュールで接続テスト

# 単一ホストへの接続テスト
ansible web01 -m ping -i inventory/hosts.ini

# グループ全体へのping
ansible webservers -m ping -i inventory/hosts.ini

# すべてのホストへのping
ansible all -m ping -i inventory/hosts.ini

# SSH接続設定を直接指定してテスト
ansible all -m ping -u ubuntu --key-file ~/.ssh/my_key -i "192.168.1.10,"

接続失敗時の一般的なエラーメッセージと対処

エラーメッセージ	原因	対処法
Connection timed out	ファイアウォール、ネットワーク到達不能	FW設定確認、pingで疎通確認
Connection refused	SSHサービスが起動していない、ポート番号違い	SSHサービス起動確認、ポート確認
Permission denied (publickey)	SSH鍵が正しくない、ユーザー名違い	鍵ファイル・ユーザー名を確認
Host key verification failed	known_hostsのホストキーが変わった	ssh-keygen -R でエントリ削除
No route to host	ルーティングの問題	ルーティングテーブルの確認

よく見落とされる設定ミス

Python インタープリターの問題

接続自体は成功しているが、その後のモジュール実行で失敗する場合はPythonの問題があります。

# インベントリでPythonパスを指定
[all:vars]
ansible_python_interpreter=/usr/bin/python3

# または ansible.cfg で
[defaults]
interpreter_python = auto_silent

sudo/become設定の問題

# playbook.yml
- hosts: webservers
  become: yes          # sudo使用
  become_user: root    # rootに昇格
  become_method: sudo  # sudo使用（デフォルト）
  vars:
    ansible_become_password: "{{ sudo_password }}"  # sudoパスワード（必要な場合）

よくある質問（FAQ）

Q1. 手動SSHは成功するのにAnsibleで「UNREACHABLE」になるのはなぜですか？

主な原因は以下のいずれかです。(1) ansible.cfgのSSH設定がSSH configの設定と異なる、(2) Ansibleが使用するSSH鍵ファイルが手動接続と異なる、(3) タイムアウト値の差、(4) ControlMasterによるソケットの問題。ansible all -m ping -vvv を実行して実際に使用されているSSHコマンドを確認してください。

Q2. 大量のホスト（100台以上）に一度にplaybookを実行するとタイムアウトが多発します

ansible.cfgの forks 値を下げて同時接続数を制限してください（デフォルト5）。また、serial キーワードでplaybookのバッチサイズを制限することも有効です。接続タイムアウトを延ばすことで解消する場合もあります。

Q3. Windows TargetにWinRMではなくSSHで接続できますか？

Windows Server 2019以降はOpenSSHサーバーが標準提供されており、AnsibleからSSHで接続することが可能です。インベントリで ansible_connection: ssh と ansible_shell_type: cmd または powershell を指定してください。

Q4. クラウド環境でEC2インスタンスに接続できません。チェックすべきことは？

(1) セキュリティグループのインバウンドルールで22番ポートが開いているか、(2) EC2インスタンスのパブリックIPが正しいか、(3) 鍵ペアのPEMファイルのパーミッションが600になっているか（chmod 600 key.pem）、(4) デフォルトユーザー名が正しいか（AMIによって ec2-user / ubuntu / admin 等が異なる）を確認してください。

Q5. Ansible Tower / AWX を使っていますが踏み台設定はどこでしますか？

Tower/AWX の「認証情報」→「ソース管理の認証情報」または「マシン」認証情報で鍵を管理し、インベントリの変数または Job Template の Extra Variables で ansible_ssh_common_args を設定します。

Q6. ControlMaster を使った場合のパフォーマンス向上はどれくらいですか？

同じホストへの複数のSSH接続を1本のソケットで多重化するため、2回目以降の接続オーバーヘッドが大幅に削減されます。100タスクのplaybookで体感できるほどの速度向上（30〜50%）が報告されています。ControlMaster=auto ControlPersist=60s の設定を推奨します。

Q7. WSL2（Windows Subsystem for Linux）からAnsibleを実行すると接続できません

WSL2はNATを経由するため、ローカルネットワークへの直接アクセスに制限がある場合があります。WSL2のネットワーク設定でmirrored networkingを有効にするか（Windows 11 22H2以降）、WSL2からホストIPを経由するように設定を見直してください。

まとめ

AnsibleのSSH接続エラーの原因は多岐にわたりますが、系統的にチェックすることで確実に特定できます。対処の優先順位をまとめます。

1. 手動SSH接続テスト: まずAnsible抜きで ssh -v で接続を確認
2. ポート・疎通確認: nc/telnetでSSHポートへの到達性を確認
3. タイムアウト延長: ansible.cfg で timeout = 30 以上に設定
4. known_hosts解消: ssh-keygen -R でホストキーをリセット
5. ファイアウォール確認: OS・クラウドセキュリティグループの両方を確認
6. 踏み台設定: ~/.ssh/config の ProxyJump で管理するのが最もシンプル
7. -vvv デバッグ: 詳細ログで実際のSSHコマンドを確認して問題を特定

Ansibleは一度設定が固まれば非常に安定したツールです。初期設定の段階でSSH接続を確実に確立し、インフラ自動化の恩恵を最大限に活かしてください。