ansible-docでドキュメントを読む

ansible-doc コマンドを使うと、モジュールの完全なドキュメントをシェル上で直接表示できます。そのため、調べるためにターミナルを離れる必要はありません。

モジュール名を渡すと、そのドキュメントを読めます。すべてのオプション、その型、必須かどうかを確認できます。モジュールを学ぶ最も速い方法です。

出力には各オプションの説明、デフォルト値、選択肢が一覧表示されます。これにより、モジュールが受け付けるキーを正確に把握できます。

-s を追加すると、モジュールの引数をすぐコピーして使えるスニペットとして表示できます。新しいタスクを作る際の出発点として最適です。

-l を付けて実行すると、インストールされているすべてのモジュールが 1 行の概要付きで一覧表示されます。grep にパイプして必要なものを見つけることもできます。

名前がわからない場合は、モジュールを一覧表示してトピックで絞り込みます。service で検索すると、関連するモジュールがすぐに見つかります。

ansible-doc はローカルにインストールされているモジュールを読み取るため、ドキュメントは常に使用中の正確なバージョンに対応します。オンライン上の古いページを参照する心配はありません。

ドキュメントには、changed や stdout など、モジュールが返す値についても説明されています。結果を register して後で使うときに役立ちます。

-t を使うと、モジュールだけでなく、ほかの種類のプラグインのドキュメントも読めます。たとえば、同じ方法で lookup プラグインや filter プラグインを調べられます。

ドキュメントのヘッダーには、モジュールのコレクションと概要が表示されます。そのため、タスクを書く前に完全修飾名を確認できます。

引数を推測する前に、まず ansible-doc を確認しましょう。10 秒の検索で、実行の失敗やわかりにくいエラーメッセージを防げます。

完全なマニュアルではなく、モジュールの引数をすぐコピーして使えるスニペットが必要です。

ansible-doc は、使用中のバージョンに対応したドキュメントをターミナルに表示します。モジュールの確認には -s、一覧表示と検索には -l を使います。📚