Ansibleのデバッグ設計入門｜-vvvフラグ・debugモジュール・assertで実行時エラーを体系的に切り分ける方法

この記事のポイント

・-vフラグで詳細ログを出し、タスク結果とモジュール引数を確認できる
・debugモジュールで変数の実際の値や条件式の評価結果を可視化できる
・assertモジュールで「期待通りの状態か」を宣言的に検証し失敗させられる
・--start-at-taskで問題箇所から実行を再開すれば検証サイクルが速くなる

# -v  : タスク結果（changed/ok/failed）と戻り値の一部を表示
# -vv : タスクのパラメータ（モジュール引数）も表示
# -vvv: 接続詳細（SSH接続先・ユーザー）・モジュールファイルのパスも表示
# -vvvv: SSHデバッグ出力まで表示（接続問題の切り分けに使う）
ansible-playbook site.yml -i inventory/hosts -v
ansible-playbook site.yml -i inventory/hosts -vvv

TASK [install httpd] *******************************************
task path: /home/ansible/site.yml:12
ok: [web01.example.com] => {
    "ansible_facts": {},
    "changed": false,
    "msg": "",
    "rc": 0,
    "results": [
        "httpd-2.4.57-11.el9.x86_64 providing httpd is already installed"
    ]
}

TASK [rhel only setup] *****************************************
skipping: [web01.example.com] => {
    "changed": false,
    "skip_reason": "Conditional result was False"
}

---
- name: 変数デバッグの例
  hosts: webservers
  tasks:
    - name: ansible_os_familyの値を確認
      debug:
        var: ansible_os_family

    - name: 複数変数をまとめて確認
      debug:
        msg: |
          OS Family: {{ ansible_os_family }}
          Distribution: {{ ansible_distribution }}
          Version: {{ ansible_distribution_version }}

TASK [ansible_os_familyの値を確認] ***
ok: [web01.example.com] => {
    "ansible_os_family": "RedHat"
}

TASK [複数変数をまとめて確認] ***
ok: [web01.example.com] => {
    "msg": "OS Family: RedHat\nDistribution: Rocky\nVersion: 9.4\n"
}

    # 問題のあるwhen条件があるタスクの直前に追加する
    - name: when条件の評価確認
      debug:
        msg: "os_family={{ ansible_os_family }}, 条件={{ ansible_os_family == 'RedHat' }}"

    - name: rhel only setup
      dnf:
        name: httpd
        state: present
      when: ansible_os_family == 'RedHat'

TASK [when条件の評価確認] ***
ok: [web01.example.com] => {
    "msg": "os_family=Debian, 条件=False"
}

    - name: パッケージ情報を取得
      command: rpm -q httpd
      register: rpm_result
      ignore_errors: true

    # 戻り値の構造全体を確認する
    - name: rpm_resultの中身を確認
      debug:
        var: rpm_result

    # 特定のフィールドだけ確認する
    - name: 終了コードと標準出力のみ確認
      debug:
        msg: "rc={{ rpm_result.rc }}, stdout={{ rpm_result.stdout }}"

Ansible実機ハンズオンはこちら

デバッグを含めたAnsibleの実践的な使い方を、RHEL環境を使って手を動かしながら学べます。
「読んで理解した」から「現場で使える」へのステップを最短で踏みたい方にお勧めです。
＞＞ Ansibleハンズオン講座の詳細を見る

    - name: httpdがインストール済みであることを確認
      assert:
        that:
          - rpm_result.rc == 0
        fail_msg: "httpdがインストールされていません（rc={{ rpm_result.rc }}）"
        success_msg: "httpdインストールを確認しました"

---
- name: 前提条件チェック
  hosts: webservers
  gather_facts: yes
  tasks:
    - name: OSのバージョン確認
      assert:
        that:
          - ansible_os_family == 'RedHat'
          - ansible_distribution_major_version | int >= 9
        fail_msg: >
          このPlaybookはRHEL/Rocky Linux 9以降が必要です。
          現在: {{ ansible_distribution }} {{ ansible_distribution_version }}

    - name: 空きディスク容量確認（/に10GB以上必要）
      assert:
        that:
          - item.size_available > 10737418240
        fail_msg: "{{ item.mount }} の空き容量が不足しています"
      loop: "{{ ansible_mounts | selectattr('mount', 'equalto', '/') | list }}"

    - name: httpdのサービス状態を取得
      service_facts:

    - name: httpdが起動・有効化されていることを確認
      assert:
        that:
          - "'httpd.service' in ansible_facts.services"
          - ansible_facts.services['httpd.service'].state == 'running'
          - ansible_facts.services['httpd.service'].status == 'enabled'
        fail_msg: >
          httpdが正常に起動していません。
          状態: {{ ansible_facts.services['httpd.service'].state | default('unknown') }}

# タスク名"httpdのサービス状態を取得"から実行を再開する
ansible-playbook site.yml -i inventory/hosts   --start-at-task="httpdのサービス状態を取得"

ansible-playbook site.yml -i inventory/hosts --step