Ansible でインフラ自動化を進めていると、必ずといっていいほど直面するのが接続エラーです。特に SSH や WinRM の接続トラブルは、エラーメッセージだけでは原因を特定しにくく、多くのエンジニアを悩ませています。

本記事では、Ansible の SSH／WinRM 接続エラーについて、認証・ポート・プロキシという 3 つの落とし穴に焦点を当て、実践的な解決方法をご紹介します。エラーコードと具体的な対処法をセットで解説していきますので、トラブルシューティングの際にすぐに活用できるでしょう。

背景

Ansible の接続メカニズム

Ansible は、エージェントレスなアーキテクチャを採用している自動化ツールです。管理対象ノードにエージェントをインストールする必要がなく、SSH（Linux/Unix）や WinRM（Windows）といった標準プロトコルを使って通信します。

以下の図は、Ansible が管理対象ノードと通信する基本的な流れを示しています。

mermaidCopy codeflowchart LR
    controller["Ansible<br/>コントローラー"] -->|SSH接続| linux["Linux/Unix<br/>ノード"]
    controller -->|WinRM接続| windows["Windows<br/>ノード"]
    controller -->|インベントリ読込| inventory[("インベントリ<br/>ファイル")]
    controller -->|Playbook実行| playbook["Playbook<br/>ファイル"]
    linux -->|タスク実行結果| controller
    windows -->|タスク実行結果| controller

図で理解できる要点：

• Ansible コントローラーから Linux は SSH、Windows は WinRM で接続
• インベントリファイルで管理対象ノードを定義
• 接続確立後、Playbook のタスクが実行される

SSH と WinRM の違い

Linux 系と Windows 系で異なる接続プロトコルを使用するため、それぞれ異なる設定と認証方式が必要になります。

#	項目	SSH（Linux/Unix）	WinRM（Windows）
1	デフォルトポート	22	5985（HTTP）, 5986（HTTPS）
2	認証方式	パスワード、SSH 鍵	Basic, Certificate, Kerberos, NTLM, CredSSP
3	暗号化	標準で暗号化	HTTP は非暗号化、HTTPS は暗号化
4	Ansible 接続タイプ	ansible_connection: ssh	ansible_connection: winrm
5	必要な Python ライブラリ	paramiko または OpenSSH	pywinrm, requests-ntlm

接続エラーが発生する主なタイミング

Ansible の接続エラーは、主に以下のタイミングで発生します。

mermaidCopy codestateDiagram-v2
    [*] --> InventoryParse: Playbook実行開始
    InventoryParse --> ConnSetup: インベントリ解析成功
    ConnSetup --> Auth: 接続確立試行
    Auth --> TaskExec: 認証成功
    TaskExec --> [*]: タスク実行完了

    InventoryParse --> ErrorInv: 設定エラー
    ConnSetup --> ErrorConn: ポート・ネットワークエラー
    Auth --> ErrorAuth: 認証エラー
    TaskExec --> ErrorTask: 実行時エラー

    ErrorInv --> [*]
    ErrorConn --> [*]
    ErrorAuth --> [*]
    ErrorTask --> [*]

接続確立のフェーズで問題が発生すると、その後のタスク実行はすべて失敗してしまいます。そのため、接続エラーの早期解決が自動化の成功に直結するのです。

課題

SSH 接続の典型的なエラー

SSH 接続でよく遭遇するエラーには、いくつかの典型的なパターンがあります。それぞれのエラーコードと発生条件を理解することが、迅速な解決につながります。

エラー 1：SSH 接続タイムアウト

jsonCopy codeUNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: ssh: connect to host 192.168.1.100 port 22: Connection timed out",
    "unreachable": true
}

発生条件：

• ネットワークが到達不可能
• ファイアウォールで SSH ポートがブロックされている
• 対象ホストが起動していない
• プロキシ設定が必要な環境で直接接続を試みている

エラー 2：SSH 認証失敗（パスワード）

jsonCopy codeUNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: Permission denied (publickey,password).",
    "unreachable": true
}

発生条件：

• パスワードが間違っている
• ユーザー名が存在しない
• SSH 設定でパスワード認証が無効化されている

エラー 3：SSH 鍵認証失敗

jsonCopy codeUNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: Permission denied (publickey).",
    "unreachable": true
}

発生条件：

• SSH 秘密鍵のパスが間違っている
• 秘密鍵のパーミッションが不適切（600 または 400 以外）
• 公開鍵が対象ホストの authorized_keys に登録されていない
• 鍵のパスフレーズが設定されているが、ssh-agent が未起動

WinRM 接続の典型的なエラー

Windows 環境特有の WinRM 接続エラーは、認証方式の多様性と SSL/TLS 設定の複雑さから、さらにトラブルシューティングが難しくなります。

エラー 4：WinRM 接続タイムアウト

jsonCopy codeUNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via winrm: HTTPConnectionPool(host='192.168.1.200', port=5985): Max retries exceeded",
    "unreachable": true
}

発生条件：

• WinRM サービスが起動していない
• ファイアウォールで WinRM ポートがブロックされている
• ネットワークが到達不可能

エラー 5：WinRM 認証失敗

jsonCopy codeUNREACHABLE! => {
    "changed": false,
    "msg": "winrm or requests is not installed: No module named 'winrm'",
    "unreachable": true
}

または

jsonCopy codeUNREACHABLE! => {
    "changed": false,
    "msg": "401 Unauthorized. Invalid credentials.",
    "unreachable": true
}

発生条件：

• pywinrm ライブラリがインストールされていない
• 認証情報（ユーザー名／パスワード）が間違っている
• 認証方式が対象ホストでサポートされていない

エラー 6：SSL/TLS 証明書検証エラー

jsonCopy codeUNREACHABLE! => {
    "changed": false,
    "msg": "ssl: certificate verify failed",
    "unreachable": true
}

発生条件：

• HTTPS（ポート 5986）使用時に自己署名証明書を使用している
• 証明書の検証が有効になっている
• 証明書の CN（Common Name）がホスト名と一致しない

プロキシ環境特有の課題

企業ネットワークなど、プロキシサーバーを経由する環境では、さらに複雑な問題が発生します。

mermaidCopy codeflowchart TD
    ansible["Ansible<br/>コントローラー"] -->|プロキシ設定| proxy["プロキシ<br/>サーバー"]
    proxy -->|転送| target["管理対象<br/>ノード"]

    ansible -.->|直接接続は不可| target

    proxy -->|認証要求| auth["プロキシ認証"]
    auth -->|認証成功| proxy
    auth -.->|認証失敗| error["接続エラー"]

プロキシ環境で発生する主な問題：

• SSH/WinRM 接続がプロキシを経由しない設定になっている
• プロキシ認証情報が設定されていない
• ProxyCommand の設定が間違っている
• 環境変数（HTTP_PROXY、HTTPS_PROXY）が Ansible に認識されていない

以下の図は、接続エラーの分類と原因の関係性を示しています。

mermaidCopy codeflowchart TB
    error["接続エラー"] --> auth_err["認証エラー"]
    error --> network_err["ネットワークエラー"]
    error --> config_err["設定エラー"]

    auth_err --> ssh_key["SSH鍵の問題"]
    auth_err --> password["パスワードの問題"]
    auth_err --> winrm_auth["WinRM認証方式"]

    network_err --> port_block["ポートブロック"]
    network_err --> timeout["タイムアウト"]
    network_err --> proxy_issue["プロキシ設定"]

    config_err --> inventory_err["インベントリ設定"]
    config_err --> ansible_cfg["ansible.cfg設定"]
    config_err --> host_vars["ホスト変数"]

解決策

SSH 接続エラーの解決手順

SSH 接続エラーを体系的に解決するためには、段階的なアプローチが効果的です。まずは基本的な接続確認から始めましょう。

ステップ 1：ネットワーク到達性の確認

接続エラーが発生したら、最初にネットワークレベルでの到達性を確認します。

bashCopy code# ホストへの疎通確認
ping -c 3 192.168.1.100

bashCopy code# SSH ポートの開放確認
nc -zv 192.168.1.100 22

または

bashCopy code# telnet での確認
telnet 192.168.1.100 22

成功時の出力例：

cssCopy codeConnection to 192.168.1.100 22 port [tcp/ssh] succeeded!

失敗時の対処法：

1. ファイアウォールルールを確認
2. セキュリティグループ（AWS など）の設定を確認
3. ネットワーク経路を traceroute で確認

ステップ 2：SSH 鍵認証の設定確認

SSH 鍵認証を使用する場合、鍵ファイルのパーミッションと配置が正しいことを確認します。

bashCopy code# 秘密鍵のパーミッション確認と修正
ls -la ~/.ssh/id_rsa

bashCopy code# パーミッションが正しくない場合は修正
chmod 600 ~/.ssh/id_rsa

bashCopy code# 公開鍵が対象ホストに登録されているか確認
ssh-copy-id -i ~/.ssh/id_rsa.pub user@192.168.1.100

インベントリでの SSH 鍵指定：

yamlCopy code# inventory.yml
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.100
      ansible_user: admin
      ansible_ssh_private_key_file: ~/.ssh/id_rsa
      ansible_connection: ssh

このインベントリ設定では、SSH 接続に必要な情報を明示的に指定しています。

ステップ 3：SSH パスワード認証の設定

パスワード認証を使用する場合は、sshpass のインストールと適切な設定が必要です。

bashCopy code# sshpass のインストール（Ubuntu/Debian）
sudo apt-get install sshpass

bashCopy code# sshpass のインストール（CentOS/RHEL）
sudo yum install sshpass

インベントリでのパスワード指定：

yamlCopy code# inventory.yml
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.100
      ansible_user: admin
      ansible_ssh_pass: '{{ vault_ssh_password }}'
      ansible_connection: ssh

パスワードは平文で記載せず、Ansible Vault で暗号化することを強く推奨します。

Ansible Vault でパスワードを暗号化：

bashCopy code# Vault ファイルの作成
ansible-vault create group_vars/all/vault.yml

Vault ファイル内に以下のように記載します：

yamlCopy code# group_vars/all/vault.yml
vault_ssh_password: 'your_secure_password'

bashCopy code# Playbook 実行時に Vault パスワードを指定
ansible-playbook -i inventory.yml playbook.yml --ask-vault-pass

ステップ 4：SSH プロキシ経由接続の設定

プロキシサーバーを経由して SSH 接続する場合は、ProxyCommand を使用します。

yamlCopy code# inventory.yml（ProxyCommand 使用）
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.100
      ansible_user: admin
      ansible_ssh_private_key_file: ~/.ssh/id_rsa
      ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q proxy-server.example.com"'

この設定により、proxy-server.example.com を経由して対象ホストに接続できます。

HTTP プロキシ経由の SSH 接続：

yamlCopy code# inventory.yml（HTTP プロキシ使用）
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.100
      ansible_user: admin
      ansible_ssh_private_key_file: ~/.ssh/id_rsa
      ansible_ssh_common_args: '-o ProxyCommand="nc -X connect -x proxy.example.com:8080 %h %p"'

nc（netcat）コマンドを使用して HTTP プロキシ経由で接続します。

ステップ 5：SSH デバッグモードでの詳細確認

接続エラーの原因が特定できない場合は、SSH のデバッグモードを有効にして詳細なログを確認しましょう。

bashCopy code# SSH デバッグモードで手動接続
ssh -vvv user@192.168.1.100

yamlCopy code# Ansible で SSH デバッグを有効化
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.100
      ansible_user: admin
      ansible_ssh_common_args: '-vvv'

bashCopy code# Ansible Playbook を詳細モードで実行
ansible-playbook -i inventory.yml playbook.yml -vvvv

デバッグ出力から、認証方式の試行順序、鍵の読み込み状況、ネットワーク接続の詳細を確認できます。

WinRM 接続エラーの解決手順

Windows ホストへの WinRM 接続は、SSH よりも設定項目が多く、認証方式も複雑です。順を追って設定していきましょう。

ステップ 1：Python ライブラリのインストール

WinRM 接続には、専用の Python ライブラリが必要です。

bashCopy code# pywinrm のインストール
pip install pywinrm

bashCopy code# 追加の認証方式をサポートする場合
pip install pywinrm[credssp]
pip install requests-ntlm
pip install requests-kerberos

インストール後、バージョンを確認します。

bashCopy code# インストール確認
pip list | grep pywinrm

ステップ 2：Windows 側の WinRM サービス設定

管理対象の Windows ホストで WinRM サービスを有効化する必要があります。

Windows ホストでの初期設定（PowerShell を管理者権限で実行）：

powershellCopy code# WinRM サービスの有効化（HTTP）
winrm quickconfig -q

powershellCopy code# WinRM リスナーの確認
winrm enumerate winrm/config/Listener

powershellCopy code# Basic 認証の有効化
Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true

powershellCopy code# 非暗号化通信の許可（テスト環境のみ）
Set-Item -Path WSMan:\localhost\Service\AllowUnencrypted -Value $true

注意：非暗号化通信は本番環境では使用せず、必ず HTTPS を使用してください。

ステップ 3：HTTPS（ポート 5986）の設定

本番環境では、セキュリティのため HTTPS 接続を使用することを強く推奨します。

自己署名証明書の作成（PowerShell）：

powershellCopy code# 自己署名証明書作成スクリプトをダウンロード
$url = "https://raw.githubusercontent.com/ansible/ansible/devel/examples/scripts/ConfigureRemotingForAnsible.ps1"
$file = "$env:TEMP\ConfigureRemotingForAnsible.ps1"

powershellCopy code# スクリプトのダウンロードと実行
Invoke-WebRequest -Uri $url -OutFile $file
PowerShell.exe -ExecutionPolicy Bypass -File $file

このスクリプトは、WinRM の HTTPS リスナーを自動的に設定してくれます。

手動で HTTPS リスナーを設定する場合：

powershellCopy code# 証明書のサムプリントを取得
$thumbprint = (New-SelfSignedCertificate -DnsName "localhost" -CertStoreLocation Cert:\LocalMachine\My).Thumbprint

powershellCopy code# HTTPS リスナーの作成
New-Item -Path WSMan:\Localhost\Listener -Transport HTTPS -Address * -CertificateThumbPrint $thumbprint -Force

powershellCopy code# ファイアウォールルールの追加
New-NetFirewallRule -DisplayName "WinRM HTTPS" -Direction Inbound -LocalPort 5986 -Protocol TCP -Action Allow

ステップ 4：Ansible インベントリでの WinRM 設定

Windows ホストへの接続情報をインベントリに記載します。

HTTP 接続の場合：

yamlCopy code# inventory.yml（HTTP - テスト環境のみ）
windows:
  hosts:
    win-server01:
      ansible_host: 192.168.1.200
      ansible_user: Administrator
      ansible_password: '{{ vault_win_password }}'
      ansible_connection: winrm
      ansible_port: 5985
      ansible_winrm_transport: basic
      ansible_winrm_server_cert_validation: ignore

HTTPS 接続の場合（推奨）：

yamlCopy code# inventory.yml（HTTPS - 本番環境推奨）
windows:
  hosts:
    win-server01:
      ansible_host: 192.168.1.200
      ansible_user: Administrator
      ansible_password: '{{ vault_win_password }}'
      ansible_connection: winrm
      ansible_port: 5986
      ansible_winrm_transport: ntlm
      ansible_winrm_server_cert_validation: ignore

ドメイン環境での Kerberos 認証：

yamlCopy code# inventory.yml（Kerberos 認証）
windows:
  hosts:
    win-server01:
      ansible_host: win-server01.example.com
      ansible_user: domain_user@EXAMPLE.COM
      ansible_connection: winrm
      ansible_port: 5985
      ansible_winrm_transport: kerberos

Kerberos 認証を使用する場合は、Ansible コントローラー側で Kerberos クライアントの設定が必要です。

ステップ 5：WinRM 接続のテスト

設定が完了したら、実際に接続テストを行います。

yamlCopy code# test-winrm.yml
---
- name: Windows接続テスト
  hosts: windows
  gather_facts: false
  tasks:
    - name: WinRM接続確認
      ansible.windows.win_ping:

bashCopy code# Playbook 実行
ansible-playbook -i inventory.yml test-winrm.yml --ask-vault-pass

成功時の出力：

markdownCopy codePLAY [Windows接続テスト] *************************************

TASK [WinRM接続確認] *****************************************
ok: [win-server01]

PLAY RECAP ***************************************************
win-server01 : ok=1 changed=0 unreachable=0 failed=0

ステップ 6：WinRM デバッグモードでの詳細確認

接続に問題がある場合は、詳細ログを確認します。

bashCopy code# 詳細モードで実行
ansible-playbook -i inventory.yml test-winrm.yml -vvvv

yamlCopy code# インベントリでデバッグを有効化
windows:
  hosts:
    win-server01:
      ansible_host: 192.168.1.200
      ansible_user: Administrator
      ansible_password: '{{ vault_win_password }}'
      ansible_connection: winrm
      ansible_winrm_operation_timeout_sec: 60
      ansible_winrm_read_timeout_sec: 70

タイムアウト値を調整することで、ネットワーク遅延環境でも安定した接続が可能になります。

プロキシ環境での接続設定

企業ネットワークなどでプロキシサーバーを経由する必要がある場合、追加の設定が必要です。

SSH のプロキシ設定（詳細版）

~/.ssh/config での設定：

perlCopy code# ~/.ssh/config
Host *.example.com
    ProxyCommand nc -X connect -x proxy.example.com:8080 %h %p
    User admin
    IdentityFile ~/.ssh/id_rsa

この設定により、example.com ドメインのすべてのホストに対してプロキシ経由で接続します。

認証付きプロキシの場合：

perlCopy code# ~/.ssh/config（認証付きプロキシ）
Host *.example.com
    ProxyCommand corkscrew proxy.example.com 8080 %h %p ~/.ssh/proxy_auth
    User admin
    IdentityFile ~/.ssh/id_rsa

corkscrew ツールを使用すると、認証付きプロキシにも対応できます。

bashCopy code# corkscrew のインストール
sudo apt-get install corkscrew

makefileCopy code# ~/.ssh/proxy_auth
proxy_user:proxy_password

bashCopy code# パーミッション設定
chmod 600 ~/.ssh/proxy_auth

WinRM のプロキシ設定

WinRM 接続でプロキシを使用する場合は、環境変数または Ansible 設定で指定します。

環境変数での設定：

bashCopy code# プロキシ環境変数の設定
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

bashCopy code# Playbook 実行
ansible-playbook -i inventory.yml playbook.yml

インベントリでのプロキシ設定：

yamlCopy code# inventory.yml
windows:
  hosts:
    win-server01:
      ansible_host: 192.168.1.200
      ansible_user: Administrator
      ansible_password: '{{ vault_win_password }}'
      ansible_connection: winrm
      ansible_winrm_proxy: http://proxy.example.com:8080

ansible.cfg でのプロキシ設定：

iniCopy code# ansible.cfg
[defaults]
http_proxy = http://proxy.example.com:8080
https_proxy = http://proxy.example.com:8080
no_proxy = localhost,127.0.0.1

この設定は、すべての Playbook 実行に適用されます。

具体例

実践例 1：マルチ OS 環境での接続設定

Linux と Windows が混在する環境で、それぞれに適切な接続設定を行う実例を紹介します。

全体構成

以下の図は、マルチ OS 環境での Ansible 接続パターンを示しています。

mermaidCopy codeflowchart TB
    controller["Ansible<br/>コントローラー"] --> linux_group["Linuxグループ"]
    controller --> windows_group["Windowsグループ"]

    linux_group --> web01["web01<br/>Ubuntu"]
    linux_group --> web02["web02<br/>CentOS"]
    linux_group --> db01["db01<br/>Ubuntu"]

    windows_group --> app01["app01<br/>Windows Server"]
    windows_group --> app02["app02<br/>Windows Server"]

    web01 -.->|SSH:22| controller
    web02 -.->|SSH:22| controller
    db01 -.->|SSH:22| controller
    app01 -.->|WinRM:5986| controller
    app02 -.->|WinRM:5986| controller

インベントリの構成

グループごとに接続設定を分けることで、管理しやすくなります。

yamlCopy code# inventory.yml
all:
  children:
    linux_servers:
      hosts:
        web01:
          ansible_host: 192.168.1.11
        web02:
          ansible_host: 192.168.1.12
        db01:
          ansible_host: 192.168.1.13
      vars:
        ansible_connection: ssh
        ansible_user: admin
        ansible_ssh_private_key_file: ~/.ssh/id_rsa
        ansible_python_interpreter: /usr/bin/python3

    windows_servers:
      hosts:
        app01:
          ansible_host: 192.168.1.21
        app02:
          ansible_host: 192.168.1.22
      vars:
        ansible_connection: winrm
        ansible_user: Administrator
        ansible_password: '{{ vault_win_password }}'
        ansible_port: 5986
        ansible_winrm_transport: ntlm
        ansible_winrm_server_cert_validation: ignore

グループ変数（vars:）を使用することで、各ホストに共通の設定を一箇所で管理できます。

Vault ファイルの作成

パスワードは必ず暗号化して管理しましょう。

bashCopy code# Vault ファイルの作成
ansible-vault create group_vars/all/vault.yml

Vault ファイル内に Windows のパスワードを記載します。

yamlCopy code# group_vars/all/vault.yml
vault_win_password: 'SecureWindowsPassword123!'

接続テスト Playbook

すべてのホストに対して接続テストを実行します。

yamlCopy code# test-all-hosts.yml
---
- name: Linux接続テスト
  hosts: linux_servers
  gather_facts: false
  tasks:
    - name: SSH接続確認（ping）
      ansible.builtin.ping:

Linux サーバーに対しては、標準の ping モジュールを使用します。

yamlCopy code- name: Windows接続テスト
  hosts: windows_servers
  gather_facts: false
  tasks:
    - name: WinRM接続確認（win_ping）
      ansible.windows.win_ping:

Windows サーバーに対しては、専用の win_ping モジュールを使用します。

bashCopy code# 実行
ansible-playbook -i inventory.yml test-all-hosts.yml --ask-vault-pass

実践例 2：プロキシ経由での複雑な接続構成

インターネット経由で AWS や Azure のリソースに接続する際、プロキシを経由する必要がある環境での設定例です。

環境構成

mermaidCopy codeflowchart LR
    ansible["Ansible<br/>コントローラー<br/>オンプレミス"] -->|プロキシ経由| proxy["HTTPプロキシ<br/>proxy.corp.com:8080"]
    proxy -->|SSH接続| aws["AWSインスタンス<br/>EC2"]
    proxy -->|WinRM接続| azure["Azureインスタンス<br/>Windows VM"]

    ansible -.->|直接接続不可| aws
    ansible -.->|直接接続不可| azure

プロキシ環境変数の設定

Ansible を実行する前に、プロキシ環境変数を設定します。

bashCopy code# プロキシ設定スクリプト
# proxy-setup.sh
export HTTP_PROXY=http://proxy.corp.com:8080
export HTTPS_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1,10.0.0.0/8

bashCopy code# スクリプトの実行
source proxy-setup.sh

SSH プロキシ設定

SSH 接続でプロキシを使用する場合は、~/.ssh/config に設定を追加します。

perlCopy code# ~/.ssh/config
Host aws-*.example.com
    ProxyCommand nc -X connect -x proxy.corp.com:8080 %h %p
    User ec2-user
    IdentityFile ~/.ssh/aws-key.pem
    StrictHostKeyChecking no

AWS インスタンスのホスト名パターンに合わせて設定しています。

インベントリ設定（プロキシ経由）

yamlCopy code# inventory-proxy.yml
all:
  children:
    aws_linux:
      hosts:
        aws-web01:
          ansible_host: aws-web01.example.com
        aws-web02:
          ansible_host: aws-web02.example.com
      vars:
        ansible_connection: ssh
        ansible_user: ec2-user
        ansible_ssh_private_key_file: ~/.ssh/aws-key.pem
        ansible_ssh_common_args: '-o ProxyCommand="nc -X connect -x proxy.corp.com:8080 %h %p"'

    azure_windows:
      hosts:
        azure-app01:
          ansible_host: azure-app01.example.com
        azure-app02:
          ansible_host: azure-app02.example.com
      vars:
        ansible_connection: winrm
        ansible_user: azureuser
        ansible_password: '{{ vault_azure_password }}'
        ansible_port: 5986
        ansible_winrm_transport: ntlm
        ansible_winrm_server_cert_validation: ignore
        ansible_winrm_proxy: http://proxy.corp.com:8080

WinRM でもプロキシ設定（ansible_winrm_proxy）を明示的に指定しています。

接続確認とトラブルシューティング

bashCopy code# AWS への接続テスト
ansible aws_linux -i inventory-proxy.yml -m ping

bashCopy code# Azure への接続テスト
ansible azure_windows -i inventory-proxy.yml -m ansible.windows.win_ping

bashCopy code# 詳細ログで接続確認
ansible aws_linux -i inventory-proxy.yml -m ping -vvvv

詳細ログから、プロキシ経由で接続しているかを確認できます。

実践例 3：エラー発生時のデバッグフロー

実際に接続エラーが発生した際の、体系的なデバッグフローを実例で示します。

エラー発生シナリオ

以下のエラーが発生したとします。

markdownCopy codeTASK [Gathering Facts] ***************************************
fatal: [webserver]: UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: Permission denied (publickey).",
    "unreachable": true
}

デバッグステップ

以下の図は、エラー解決のための体系的なデバッグフローを示しています。

mermaidCopy codeflowchart TD
    start["接続エラー発生"] --> check_network["ステップ1<br/>ネットワーク確認"]
    check_network -->|OK| check_auth["ステップ2<br/>認証情報確認"]
    check_network -->|NG| fix_network["ネットワーク修正"]

    check_auth -->|OK| check_key["ステップ3<br/>SSH鍵確認"]
    check_auth -->|NG| fix_auth["認証情報修正"]

    check_key -->|OK| check_config["ステップ4<br/>設定ファイル確認"]
    check_key -->|NG| fix_key["鍵ファイル修正"]

    check_config -->|OK| check_debug["ステップ5<br/>デバッグモード実行"]
    check_config -->|NG| fix_config["設定修正"]

    check_debug --> resolve["問題解決"]

    fix_network --> check_network
    fix_auth --> check_auth
    fix_key --> check_key
    fix_config --> check_config

ステップ 1：ネットワーク到達性の確認

bashCopy code# ホストへの到達確認
ping -c 3 webserver

bashCopy code# SSH ポートの確認
nc -zv webserver 22

ステップ 2：SSH 手動接続テスト

bashCopy code# 手動で SSH 接続を試す
ssh -i ~/.ssh/id_rsa admin@webserver

手動接続が成功する場合は、Ansible の設定に問題があります。手動接続も失敗する場合は、SSH の設定に問題があります。

ステップ 3：SSH 鍵の確認

bashCopy code# 秘密鍵のパーミッション確認
ls -la ~/.ssh/id_rsa

bashCopy code# パーミッションが正しくない場合は修正
chmod 600 ~/.ssh/id_rsa

bashCopy code# 公開鍵が対象ホストに登録されているか確認
ssh-keygen -l -f ~/.ssh/id_rsa.pub

bashCopy code# 対象ホストの authorized_keys を確認
ssh -i ~/.ssh/id_rsa admin@webserver "cat ~/.ssh/authorized_keys"

ステップ 4：Ansible インベントリの確認

bashCopy code# インベントリの内容を表示
cat inventory.yml

yamlCopy code# 正しい設定例
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.100
      ansible_user: admin
      ansible_ssh_private_key_file: ~/.ssh/id_rsa
      ansible_connection: ssh

ステップ 5：デバッグモードで実行

bashCopy code# Ansible を最大詳細度で実行
ansible-playbook -i inventory.yml playbook.yml -vvvv

デバッグ出力から、以下の情報を確認します：

#	確認項目	デバッグ出力での確認内容
1	使用される SSH 鍵	using SSH key file で始まる行
2	接続先ホスト	ESTABLISH SSH CONNECTION FOR USER で始まる行
3	認証方式	Authentication methods で始まる行
4	エラーの詳細	fatal: または ERROR! で始まる行
5	SSH コマンド	SSH: EXEC で始まる行

ステップ 6：問題の特定と解決

デバッグ出力から、鍵ファイルのパスが間違っていることが判明した場合の修正例です。

yamlCopy code# inventory.yml（修正前）
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.100
      ansible_user: admin
      ansible_ssh_private_key_file: ~/ssh/id_rsa # パスが間違っている

yamlCopy code# inventory.yml（修正後）
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.100
      ansible_user: admin
      ansible_ssh_private_key_file: ~/.ssh/id_rsa # 正しいパス

bashCopy code# 再度実行
ansible-playbook -i inventory.yml playbook.yml

このように段階的にデバッグすることで、問題を確実に特定し解決できます。

まとめ

Ansible の SSH／WinRM 接続エラーは、認証・ポート・プロキシという 3 つの主要な原因に分類できます。本記事では、それぞれのエラーパターンと体系的な解決方法をご紹介しました。

重要なポイント：

• SSH 接続では、鍵認証のパーミッション設定とプロキシ設定が重要です
• WinRM 接続では、pywinrm のインストールと Windows 側のサービス設定が必須です
• プロキシ環境では、環境変数と ProxyCommand の適切な設定が接続成功の鍵となります
• デバッグは段階的に行い、ネットワーク → 認証 → 設定の順で確認することで効率的に問題を特定できます

接続エラーが発生した際は、本記事で紹介したエラーコードと解決手順を参考に、冷静に一つずつ確認していくことで、必ず解決できるでしょう。エラーメッセージをしっかり読み、デバッグモードを活用することで、トラブルシューティングのスキルも向上していきます。

Ansible の接続問題を克服することで、より安定した自動化環境を構築できますね。今回ご紹介した設定やデバッグ手法が、皆様の Ansible 運用の助けとなれば幸いです。

関連リンク

• Ansible 公式ドキュメント
• Ansible Connection Methods
• WinRM Setup for Ansible
• Ansible Vault ドキュメント
• pywinrm GitHub リポジトリ
• SSH Config File Documentation