Ansibleドキュメントを活用しよう！モジュールの調べ方

こんにちは、最近ロードバイクにハマっているひよこ大佐こと八木澤です。 Red HatでAnsibleのTechnical Support Engineerをしています。

AnsibleやAnsible Towerに関わるトラブルの解決や、より皆様が快適にAnsibleを活用できるようなお手伝いをしています。

Ansibleのドキュメントとは？

下記ページにて公開されている公式ドキュメントです。英語のみですがモジュールの情報やPlaybookの書き方など、 Ansibleを使う上で必要な情報の多くはこのドキュメントで確認することができます。

https://docs.ansible.com/

f:id:hiyokotaisa:20181025120912p:plain

また、このドキュメントの情報は、Ansibleがインストールされているマシンであれば$ ansible-doc <モジュール名> コマンドで同じ内容を確認することができますので、あわせて活用してみてください。

モジュールの調べ方

Ansibleでは、Playbookに基づいてターゲットノードの構成を変更します。そのなかで「モジュール」は、Playbookにおいて実際の設定変更やコマンドの実行等、Ansibleが利用できる機能群を指します。 Playbookを書く際には、「どんなモジュールが使えるのか」「どんなパラメータを設定する必要があるのか」といったモジュールに関わる部分は必ず調べる必要があります。

初めてPlaybookを書く方は何から手を付ければいいのか悩んでしまうかもしれませんが、まず下記ページで該当するモジュールを探しましょう。

https://docs.ansible.com/ansible/latest/modules/modules_by_category.html

f:id:hiyokotaisa:20181025121017p:plain

カテゴリ分けされており、自分の実現したい機能に応じてモジュールを探すことができます。ここでは例として「yum」モジュールのページを見てみましょう。 https://docs.ansible.com/ansible/latest/modules/yum_module.html#yum-module

Synopsis

このモジュールの概要です。yumモジュールの場合は、yumパッケージマネージャーを使用して、パッケージのインストールやアップグレード、削除などを行います。

Requirements

このモジュールの依存関係が書かれています。実行にあたりpythonのyumモジュールが必要です。

Parameters

このモジュールを使用するにあたって、設定する必要のあるパラメーター群です。

f:id:hiyokotaisa:20181025121937j:plain

Parameter

Playbook内で定義するパラメーター名です。 (added in 2.7)などと記載されている場合は、記載バージョンから追加されたパラメーターです。以前のバージョンのAnsibleでは使用できませんので注意が必要です。

Choices/Defaults

パラメーターに対して設定できる値です。青色で記載されているものはDefault値ですので、何も指定しなければ青色の値が使用されます。

Comments

各パラメーターの解説です。設定値ごとの挙動や細かな注意事項などが記載されています。

Notes

このモジュールを使用するにあたっての注意事項が記載されています。モジュールを使用する前に必ず目を通しておいたほうがよいでしょう。 f:id:hiyokotaisa:20181025122815j:plain

例えば「yumモジュールではloopを使用すると個別に処理が実行されるため、list形式でnameオプションに指定したほうが効率的」といった説明が書かれています。

Examples

f:id:hiyokotaisa:20181025122137j:plain

モジュールの使用例が記載されています。通常は複数の使用例が記載されており、「name」に簡単な説明が書かれていることがほとんどです。

- name: install the latest version of Apache
  yum:
    name: httpd
    state: latest

例えば、上記例では、yumモジュールで最新バージョンのApacheをインストールします。このExamplesはPlaybookを書くうえで非常に参考になります。書き方がわからない場合は、まずExamplesを確認しましょう。

Maintenance

このモジュールのメンテナンス状況が記載されています。 yumモジュールは「core」モジュールであり、Red HatのCore Teamによってメンテナンスされています。

各モジュールのステータスの意味は、下記で確認することができます。 https://docs.ansible.com/ansible/latest/user_guide/modules_support.html#modules-support

Tips

以前のバージョンのAnsibleを使用していて、「今のバージョンのモジュールが2.7でどう変わったか確認したい」といったときがあります。その際は、各ドキュメントのURL「https://docs.ansible.com/ansible/」に続けてバージョンを記載してあげることで、そのバージョンのAnsibleのドキュメントを確認することができます。

※Ansible 2.4以前のドキュメントを確認する場合は、下記URLから確認してください。

https://docs.ansible.com/ansible/<確認したいバージョン>/yum_module.html

例えば、Ansible 2.6のときのyumモジュールのページは下記のようになります。 https://docs.ansible.com/ansible/2.6/modules/yum_module.html

その時の最新版を確認したい場合は「latest」と指定すると、最新のドキュメントを確認することができます。