JSON を返し changed を遵守する

モジュールが終了するときは、Ansible に JSON 形式の結果を渡す必要があります。これによって、コントローラーはホスト上で何が起きたかを把握できます。

成功時には module.exit_json を呼び出します。結果を JSON として出力し、適切な終了コードでモジュールを正常に終了します。

changed は常に正確に報告してください。これはシステムを変更したかどうかを Ansible に伝え、出力の ok と changed の表示を決めます。

changed を正しく扱うには、まず現在の状態を読み取ります。すでに目標と一致している場合は、changed=False に設定して何もしません。

exit_json には任意のキーを追加でき、それらはタスクの結果に表示されます。ユーザーは後続の処理でそのデータを登録して再利用できます。

問題が発生した場合は、明確なメッセージを添えて module.fail_json を呼び出します。Ansible はタスクを失敗として扱い、そのテキストを表示します。

print や生の stdout は使用しないでください。Ansible が受け取るのは最後の JSON オブジェクトだけなので、余分な print が結果を 破損 させ、タスクが失敗します。

各モジュールは、exit_json または fail_json のいずれか 1 回だけで終了します。どちらも SystemExit を発生させるため、その後の処理は実行されません。

実行した内容を説明する、わかりやすい msg を結果に含めてください。適切なメッセージがあれば、わかりにくい実行結果も読みやすくなります。

コアモジュールと同じような出力にします。changed を報告し、意味のあるフィールドを返し、理由を示して明確に失敗させてください。一貫性が信頼につながります。

ハンドラー、条件分岐、登録済み変数はすべて、モジュールの JSON を読み取ります。changed を正しく設定することが、モジュールを Ansible の一員として適切に動作させる鍵です。

何も変更しなかった場合に、モジュールが何を報告すべきか考えてみてください。

成功時は exit_json、エラー時は fail_json で終了し、changed を正直に報告して、生の出力を決して表示しません。これがモジュールの結果プロトコルです。📦