【Ansible講座 付録】エラーと戦う技術。デバッグモジュール活用とトラブルシューティング完全ガイド

「赤い文字」にパニックになるのは、今日で終わりにしよう。

こんにちは！「LINUX工房」管理人の「リナックス先生」です。
全8回のAnsible講座、完走おめでとうございます。
もうあなたは、Playbookを書いてサーバーを自動構築できる立派な自動化エンジニアです。

しかし、現実は甘くありません。
「昨日まで動いていたPlaybookが、今日は真っ赤なエラーを吐いて止まる」
「変数の値が思った通りに入っていなくて、設定ファイルが空っぽになる」
そんなトラブルに必ず遭遇します。

本記事では、AlmaLinux 9 をベースに、詳細ログオプション（-vvv）の読み方、変数を可視化する debug モジュール、前提条件をチェックする assert モジュール、そしてDockerコンテナの操作まで、実践的なテクニックを網羅します。

---

第1章：詳細モード「-v」で裏側を覗く

Ansibleのトラブルシューティングにおいて、最初にやるべきことは「詳細モード（Verbosity Mode）」での実行です。
オプション -v をつける数によって、表示される情報の細かさが変わります。

1. -v (レベル1: 結果の詳細)

ansible-playbook site.yml -v

タスクが失敗したとき、通常は「FAILED!」だけですが、-v をつけると「どのモジュールが」「どんな結果を返したか（標準出力など）」が表示されます。
まずはこれをつけましょう。

2. -vvv (レベル3: SSH接続のデバッグ)

ansible-playbook site.yml -vvv

通称「スリー・ブイ」。SSH接続の確立プロセスまで全て表示されます。
「Unreachable（到達不能）」エラーが出たときは、迷わずこれを使いましょう。

チェックポイント:

• どの秘密鍵を使っているか？ (IdentityFile)
• どのユーザーで接続しようとしているか？ (User)
• sudoパスワードは通っているか？

これらがログの中に明確に記述されています。

---

第2章：変数を可視化する「debug」モジュール

「テンプレートで設定ファイルを作ったけど、値が空っぽだった」「if文が意図した通りに分岐しない」。
そんな時は、変数の値が期待通りに入っていないことが多いです。

プログラミングで言う print() デバッグをするために、debug モジュールを使います。

基本の使い方

- name: Check variable value
  ansible.builtin.debug:
    var: http_port
    # またはメッセージ付きで
    # msg: "The port is {{ http_port }}"

応用：register との組み合わせ

コマンドの実行結果を変数に入れて（register）、その中身を確認するパターンは頻出です。

- name: Check Apache Status
  ansible.builtin.command: systemctl status httpd
  register: apache_status
  ignore_errors: true  # エラーでも止まらないようにする

- name: Show Status
  ansible.builtin.debug:
    var: apache_status.stdout_lines

stdout_lines を指定すると、改行コードで整形されたリスト形式で見やすく表示されます。

---

第3章：防御的Playbook「assert」モジュール

エラーが出てから慌てるのではなく、「実行前に前提条件をチェックして、ダメなら親切なメッセージを出して止める」のが、プロのPlaybookです。
これには assert モジュールを使います。

使用例1：OSバージョンのチェック

「このPlaybookはAlmaLinux 9専用です」という場合。

- name: Check OS version
  ansible.builtin.assert:
    that:
      - ansible_distribution == "AlmaLinux"
      - ansible_distribution_major_version == "9"
    fail_msg: "This playbook only supports AlmaLinux 9!"
    success_msg: "OS check passed."

条件（that）を満たさない場合、fail_msg を表示して即座に停止します。
謎のエラーで途中停止してサーバーを半端な状態にするより、最初に止める方が100倍マシです。

使用例2：必須変数のチェック

「パスワード変数が定義されていなかったら止める」場合。

- name: Check password variable
  ansible.builtin.assert:
    that:
      - db_password is defined
      - db_password | length > 8
    fail_msg: "db_password is not defined or too short!"

---

第4章：エラーハンドリング（block / rescue / always）

プログラミング言語にある try - catch - finally と同じことが、Ansibleでもできます。
「処理が失敗したら、ロールバック（元に戻す）処理をする」といった高度な制御が可能です。

構文の例

- name: Dangerous Update Operation
  block:
    - name: Upgrade Database
      ansible.builtin.shell: /usr/local/bin/upgrade_db.sh
      
    - name: Restart Database
      ansible.builtin.service:
        name: mariadb
        state: restarted

  rescue:
    - name: Revert Database (if failed)
      ansible.builtin.shell: /usr/local/bin/restore_db_backup.sh
      
    - name: Send Alert to Slack
      ansible.builtin.uri:
        url: https://hooks.slack.com/...
        method: POST
        body: '{"text": "DB Upgrade Failed! Rolled back."}'

  always:
    - name: Clean up temporary files
      ansible.builtin.file:
        path: /tmp/upgrade.log
        state: absent

• block: メインの処理。ここでエラーが起きると、即座に rescue に飛びます。
• rescue: エラーが起きた時だけ実行される処理（リカバリ、通知など）。
• always: 成功・失敗に関わらず、最後に必ず実行される処理（後始末など）。

---

第5章：【発展】DockerコンテナをAnsibleで操る

最近の現場では、サーバーに直接Apacheを入れるのではなく、Dockerコンテナとして立ち上げることも増えています。
Ansibleには community.docker コレクション があり、docker-compose.yml を書くのと同じ感覚でコンテナ管理ができます。

1. 準備（コレクションのインストール）

コントロールノード（実行する側）にコレクションを入れます。

ansible-galaxy collection install community.docker

2. Dockerコンテナを起動するPlaybook

Nginxのコンテナを立ち上げる例です。

- name: Start Nginx Container
  hosts: docker_servers
  become: true
  tasks:
    - name: Install Docker (if not exists)
      ansible.builtin.dnf:
        name: docker
        state: present
    
    - name: Ensure Docker is running
      ansible.builtin.systemd:
        name: docker
        state: started
        enabled: true

    - name: Run Nginx Container
      community.docker.docker_container:
        name: my-nginx
        image: nginx:latest
        state: started
        restart_policy: always
        ports:
          - "80:80"
        volumes:
          - /var/www/html:/usr/share/nginx/html:ro

docker run コマンドを叩くのと違い、「コンテナが起動している状態を保証する（冪等性）」点がメリットです。
設定変更があった場合だけコンテナを再作成（Recreate）してくれます。

---

第6章：よくあるエラー集（FAQ）

初心者が必ずハマるエラーと、その解決策をまとめました。

Q1. “Permission denied (publickey,gssapi-keyex,gssapi-with-mic)”

原因: SSH接続に失敗しています。
対策:
1. ssh user@host で手動ログインできるか確認。
2. 公開鍵が相手の ~/.ssh/authorized_keys にあるか確認。
3. ansible.cfg の private_key_file が正しいか確認。

Q2. “ModuleNotFoundError: No module named ‘docker'”

原因: ターゲットサーバー側のPythonに docker ライブラリが入っていません（Ansibleモジュールが依存しています）。
対策: pip install docker または dnf install python3-docker を実行するタスクを追加してください。

Q3. “sudo: a password is required”

原因: become: true を使っていますが、sudoパスワードなしで実行できる設定になっていません。
対策:
1. visudo で NOPASSWD 設定をする。
2. または、ansible-playbook -K で実行時にパスワードを入力する。

Q4. “Syntax Error while loading YAML”

原因: YAMLのインデントがずれています。全角スペースが入っているかもしれません。
対策: VS CodeのYAML拡張機能を使ってチェックしてください。コロンの後のスペース忘れもよくある原因です。

---

まとめ：エラーログは「成長の糧」

今回の付録では、トラブルシューティングの技術と、発展的なDocker連携について学びました。

今回の重要ポイント：

• -vvv は友達。SSH接続エラーはここを見れば全部わかる。
• debug モジュールで変数を可視化せよ。
• assert で前提条件をチェックし、block/rescue で失敗に備える。
• AnsibleでDockerコンテナも管理できる（インフラのモダン化）。

エラーが出ると焦ってしまいますが、Ansibleのエラーメッセージは比較的親切です。
「何が起きたか」を冷静に読み解き、一つずつ解決していくプロセスこそが、エンジニアとしてのスキルを最も高めてくれます。

これで、Ansible講座は本当の完結です。
あなたのPlaybookが、チームを助け、サービスを支える堅牢なインフラになることを願っています。
Happy Automating!