Ansibleの「止まらないエラー」を制する：debugger: on_failed が変えるインフラ運用の作法
大規模なIaCプロジェクトを運用していると、必ず直面する「最後の1マイルの壁」がある。数千行のPlaybook、複雑にネストされたRole、そして疎通確認が困難なエッジケース。一度失敗するたびに `ansible-playbook -i inventory site.yml` を叩き直し、数分間のセットアップ時間を待つ……そんな「暗黒の待ち時間」を繰り返していないだろうか。
Ansibleは単なる自動化ツールではない。適切に扱えば、デバッグプロセスそのものをコード化できる。今回は、現場で泥臭く戦うエンジニアのために、`debugger: on_failed` を活用した「死なない」デバッグ手法を伝授する。
—
1. なぜ標準のログ出力だけでは足りないのか
デフォルトのAnsibleの出力は、あくまで「事後の報告書」に過ぎない。
- コンテキストの喪失: 失敗した瞬間、メモリ上に展開されていた複雑な `dict` や `list` の中身が、スタックトレースの中では断片的にしか見えない。
- 再試行のコスト: 特定のタスクで失敗した際、その前の処理を再実行せずに「変数の値だけを変えて即座に再試行」することが標準ではできない。
この「再実行の重さ」が、エンジニアの試行錯誤を奪い、勘に頼った修正を誘発する。これを解決するのが、タスクレベルで動的に介入する `debugger` モジュールだ。
—
2. `debugger: on_failed` という「外科手術」
`debugger: on_failed` を設定すると、タスクが失敗した瞬間にAnsibleが処理を中断し、そのコンテキスト内で対話型シェルを起動する。
実践的な設定例
- name: 複雑なAPI設定を反映させるタスク
uri:
url: “https://api.internal/v1/config”
method: POST
body: “{{ complex_payload }}”
register: api_result
# 失敗時にデバッガを起動して、変数の状態をその場で確認・修正する
debugger: on_failed
このタスクが失敗すると、ターミナルが `[task debug]` モードに切り替わる。ここで `p task.args` を実行すれば、実際に投げられたリクエストの内容が丸裸になる。
—
3. 対話型シェルによる「その場修正」の極意
デバッガに入ったら、以下のコマンドで戦況を変える。
- `p task.args`: 送信した引数を確認。インデントミスや変数の展開漏れを一発で見抜く。
- `p result`: 失敗したタスクの戻り値を確認。APIのレスポンスやエラーメッセージを詳細に追える。
- `p hostvars[‘target_host’][‘some_variable’]`: 他のホストの変数にアクセス。環境間の差異によるバグを特定する。
- `task.args[‘body’] = {‘new’: ‘value’}`: これが最強の機能だ。 変数を実行中に書き換え、`redo` コマンドでそのタスクだけを再実行できる。
現場の神テクニック:
エラー箇所が特定できたら、修正した変数で即座に `redo` して成功させる。これで、Playbook全体を最初から回す時間を数分単位で節約できる。
—
4. チームの生産性を底上げする「設定のベストプラクティス」
個人のハックをチームの標準にするための設定とルールを共有する。
隠れた神設定：`ansible.cfg`
プロジェクトのルートに以下の設定を置くことで、開発効率を劇的に向上させる。
[defaults]
実行時間を計測し、遅いタスクを可視化する
callback_whitelist = profile_tasks
デバッグ時はstdoutを読みやすくする
stdout_callback = yaml
冪等性を確認するために、常にdiffを取る
diff_always = True
[ssh_connection]
大規模環境ではパイプライン化を有効化して高速化
pipelining = True
チームで守るべきルール
1. 変数定義の明示化: `group_vars/all.yml` に `debug: false` を定義し、デバッグ時のみ環境変数でオーバーライドする。
2. 冪等性の担保: どんなに複雑なタスクでも、`changed_when: false` を安易に使わない。必ず「何が変わったか」をAnsibleに理解させる。
3. モジュールの選定: `shell` や `command` は最終手段。`lineinfile` や `blockinfile` ではなく、可能な限り `template` か専用モジュール（`k8s`, `docker_container` 等）を使う。
—
5. 最後に：エンジニアへの提言
Ansibleで大規模環境を管理する際、最も恐ろしいのは「見えないところで何かを変えてしまうこと」だ。`debugger: on_failed` を使いこなすことは、単なるトラブルシューティングではない。それは、自分の書いたコードがシステム上でどう振る舞うのかを、リアタイムに「観察」し「対話」するスキルだ。
Playbookは読み書きするだけではない。実行中に介入し、制御する。この感覚を掴んだ時、あなたのIaC運用レベルは一段上の「エンジニアリング」へと昇華するはずだ。
さあ、次はどのタスクをデバッグしようか。現場のコードは、常にあなたと対話したがっている。