DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ

シェルおよびコマンドモジュールのデバッグ実践ガイド

register、stdout、stderr、rc、failed_when、changed_whenの例を使ってAnsibleのシェルおよびコマンドの失敗をデバッグします。

シェルおよびコマンドモジュールのデバッグ実践ガイド

Ansibleのcommandモジュールとshellモジュールは、専用のモジュールが存在しない場合に便利ですが、デバッグが難しい場合があります。タスクが失敗しても、自分でコマンド出力をキャプチャしない限り、リターンコードしか表示されないことがあります。

このガイドでは、rc、stdout、stderrを確認し、failed_whenとchanged_whenを使用してAnsibleが実際の結果を報告するようにすることで、失敗したシェルおよびコマンドモジュールをデバッグする方法を説明します。

Command vs. Shell: 違いを理解する

デバッグに取り掛かる前に、2つのモジュールの基本的な違いを理解することが重要です。実行環境が障害モードに影響を与えるからです。

ansible.builtin.command

このモジュールは、標準のシェル環境をバイパスしてコマンドを直接実行します。そのため、変数展開、グロビング、パイプ（|）、リダイレクト（>）などのシェル機能を回避できるため、より安全で予測可能です。

ベストプラクティス: タスクがシンプルでシェル機能を必要としない場合は、commandを使用します。

ansible.builtin.shell

このモジュールは、リモートホストの標準シェル（/bin/shまたは同等のもの）を介してコマンドを実行します。これは、複雑な操作、環境変数、または標準的なシェル構文（例：cd /tmp && ls -l）を使用する場合に必要です。

警告: shellは環境に依存するため、PATH設定、隠れた環境変数、複雑な引用符に関連する予測不能な障害が発生しやすくなります。

Ansibleコマンド失敗の構造

デフォルトでは、Ansibleはcommandまたはshellモジュールタスクの成功または失敗を、プロセスの**リターンコード（RC）**に基づいて判断します。

リターンコード（RC） 解釈
rc = 0 成功（タスクは続行）
rc != 0 失敗（タスクは即座に停止、ホストは失敗とマーク）

ただし、この単純なチェックでは、実際のスクリプトのニュアンスを捉えきれないことがよくあります。コマンドがRC 0を返しても望ましくない結果（論理的な失敗）を生じる場合や、コマンドが予期された非ゼロのRCを返す場合（例：grepは一致するものがない場合に1を返す）があります。

これらのニュアンスを処理するには、出力をキャプチャし、条件付きで失敗状態を制御する必要があります。

ステップ1: registerを使用したコマンド出力のキャプチャ

効果的なデバッグの最初のステップは、registerキーワードを使用して、利用可能なすべての出力ストリームをAnsible変数にキャプチャすることです。これにより、リターンコード、標準出力、標準エラーを検査できます。

初期テスト中に、非ゼロのリターンコードでプレイブックが即座に停止するのを防ぐために、一時的にignore_errors: yesを使用すると便利です。

- name: 信頼性の低い可能性のあるコマンドを実行し、結果をキャプチャする
  ansible.builtin.shell: | 
    /usr/local/bin/check_config.sh 2>&1 || exit 1
  register: cmd_output
  ignore_errors: yes  # 一時的にRC != 0を許可して続行

登録されると、cmd_output変数にはいくつかの有用なキーが含まれます。最も注目すべきものは以下の通りです。

  • cmd_output.rc: 整数のリターンコード。
  • cmd_output.stdout: 標準出力ストリーム。
  • cmd_output.stderr: 標準エラー出力ストリーム。
  • cmd_output.failed: Ansibleが現在タスクを失敗と見なしているかどうかを示すブール値。

ステップ2: debugを使用したキャプチャデータの検査

失敗したタスクの直後にdebugモジュールを使用して、登録された変数の内容を検査します。これにより、真の技術的な障害（例：コマンドが見つからない）と論理的な障害（例：スクリプトは実行されたが内部エラーを報告した）を区別するのに役立ちます。

- name: デバッグ用にキャプチャした完全な出力を表示する
  ansible.builtin.debug:
    var: cmd_output
    # 'when'を使用して、タスクが失敗した場合のみ表示し、出力を整理する
  when: cmd_output.failed is defined and cmd_output.failed

- name: stderrの内容を強調表示する
  ansible.builtin.debug:
    msg: "キャプチャしたSTDERR: {{ cmd_output.stderr }}"
  when: cmd_output.stderr | length > 0

完全な出力を検査することで、真の失敗を示す特定のエラーメッセージやパターンを特定できます。

ステップ3: failed_whenを使用したデフォルトの失敗動作のオーバーライド

failed_when条件は、複雑なシェルモジュールの結果をデバッグおよび管理するための最も強力なツールです。これにより、デフォルトのリターンコードに関係なく、Jinja2式を使用してカスタムロジックを定義し、タスクを失敗としてマークするかどうかを決定できます。

シナリオA: 予期される非ゼロのリターンコードの処理

一部のユーティリティは、予期される結果に対して非ゼロのコードを返します。たとえば、grepは一致するものがない場合は1を返し、実際のエラーの場合は1より大きい値を返します。

- name: 設定が存在するか確認するが、存在しない場合は失敗しない
  ansible.builtin.command: grep -q '^feature_enabled=true' /etc/myapp.conf
  register: grep_result
  failed_when: grep_result.rc > 1
  changed_when: false

シナリオB: 論理エラーでの失敗（RC=0だが出力が悪い）

内部エラーが発生してもスクリプトが常にRC=0を返すが、特定のエラー文字列をstdoutまたはstderrに出力する場合は、failed_whenを使用してその文字列をキャッチします。

- name: データベース接続スクリプトの検証
  ansible.builtin.shell: /opt/scripts/db_connect_test.sh
  register: db_result
  # stdoutとstderrの両方で一般的なエラーフレーズをチェック
  failed_when: >
    ('Connection refused' in db_result.stderr) or
    ('Authentication failure' in db_result.stdout)

シナリオC: RCと出力チェックの組み合わせ

堅牢なチェックのために、論理演算子（and、or、括弧）を使用してリターンコードとコンテンツチェックを組み合わせます。

- name: デプロイメントログの確認
  ansible.builtin.shell: tail -n 50 /var/log/deployment.log
  register: log_check
  # RCが非ゼロの場合、または成功した出力に'FATAL'という単語が含まれている場合に失敗
  failed_when: log_check.rc != 0 or 'FATAL' in log_check.stdout

ヒント: failed_whenを使用する場合、明示的に失敗をログに記録してプレイを続行したい場合を除き、通常はignore_errors: yesを削除する必要があります。

信頼性の高いコマンド実行のためのベストプラクティス

複雑なデバッグの必要性を最小限に抑えるために、commandまたはshellを使用するタスクを作成する際は、以下の基準に従ってください。

1. 常に絶対パスを使用する

リモートユーザーの$PATHに依存しないでください。実行可能ファイルへのフルパスを常に指定してください（例：pythonだけでなく/usr/bin/python）。これにより、一貫性のない環境や実行パスの微妙な違いによって引き起こされる障害を回避できます。

2. シェルロジックよりも条件文を活用する

shellモジュール内で複雑なシェルロジック（||や&&など）を使用する代わりに、Ansibleのネイティブ条件文（when:、failed_when:、changed_when:）とregisterキーワードを活用してください。これにより、プレイブックのロジックが透過的になり、デバッグが容易になります。

3. 変更検出を明示的に制御する（changed_when）

デフォルトでは、commandとshellは、リターンコードが0の場合にタスクをchangedとしてマークします。スクリプトが実行されてもシステムに変更を加えない場合（例：単純なステータスチェック）、changed_whenを使用して、タスクがいつ変更をもたらすかを手動で定義する必要があります。

- name: ディスク容量を確認する（'changed'にならないようにする）
  ansible.builtin.command: df -h /data
  changed_when: false

4. 可能な場合はステートモジュールを使用する

ファイルの存在確認、サービスの起動/停止、パッケージのインストールにshellを使用している場合は、専用のAnsibleモジュール（例：ansible.builtin.stat、ansible.builtin.service、ansible.builtin.package）を探してください。専用モジュールは内部で冪等性とエラーチェックを処理するため、デバッグの労力を大幅に削減できます。

最終的なポイント

シェルまたはコマンドタスクが失敗した場合は、まず結果をキャプチャし、rc、stdout、stderrを検査してから、実際の成功条件をfailed_whenにエンコードします。タスクが安定したら、changed_whenを追加して、ステータスチェックがすべてのプレイブック実行で誤った変更を表示しないようにします。