てくなべ (tekunabe)

ansible / network / automation / StackStorm

[Ansible] オフライン状態でモジュールの詳細をなど調べる方法(ansible-doc/ansible-config)

■ はじめに

Playbook を書いていく過程で、Ansible の公式ドキュメントを閲覧したり、インターネットで検索したりして、調べることが多いと思います。

しかし、もしインターネットにつながっていない状態で調べことをしたい時はどのようにしたらよいでしょうか。

この記事では、オフライン状態(ここではインターネット未接続状態のこと指します)で、Ansible について調べる方法をいくつかご紹介します。対応する公式ドキュメントのページもあわせてご紹介します。

動作確認環境: Ansible 2.7.8


■ モジュール

モジュールの詳細情報を知りたい

モジュール名は分かっているけれど、オプションの名前やサンプルを確認したい時に調べる方法です。

ansible-doc [モジュール名]
  • 実行例: ios_config モジュールの詳細を表示する
$ ansible-doc ios_config

 IOS_CONFIG    (/home/vagrant/ansible2780/lib/python2.7/site-packages/ansible/modules/network/ios/ios_confi

        Cisco IOS configurations use a simple block indent file syntax for segmenting
        configuration into sections.  This module provides an implementation for
        working with IOS configuration sections in a deterministic way.

(...略...)

EXAMPLES:

- name: configure top level configuration
  ios_config:
    lines: hostname {{ inventory_hostname }}

- name: configure interface settings
  ios_config:
    lines:
      - description test interface
      - ip address 172.31.1.1 255.255.255.0
    parents: interface Ethernet1

(...略...)

公式ドキュメントでは、こちらの ios_config モジュールのページを確認します。

モジュール名の一部からモジュール名を特定したい

モジュール名の一部しか分かっていないけれど、どのモジュールかを特定したい時に調べる方法です。

ansible-doc -l | grep [正規表現]
  • 実行例: ios_ から始まるモジュール名の一覧を表示する
$ ansible-doc -l | grep ^ios_
ios_banner                                           Manage multiline banners on Cisco IOS devices
ios_command                                          Run commands on remote devices running Cisco IOS
ios_config                                           Manage Cisco IOS configuration sections
ios_facts                                            Collect facts from remote devices running Cisco IO...
ios_interface                                        Manage Interface on Cisco IOS network devices
ios_l2_interface                                     Manage Layer-2 interface on Cisco IOS devices.
ios_l3_interface                                     Manage Layer-3 interfaces on Cisco IOS network dev...
ios_linkagg                                          Manage link aggregation groups on Cisco IOS networ...
ios_lldp                                             Manage LLDP configuration on Cisco IOS network dev...
ios_logging                                          Manage logging on network devices
ios_ping                                             Tests reachability using ping from Cisco IOS netwo...
ios_static_route                                     Manage static IP routes on Cisco IOS network devic...
ios_system                                           Manage the system attributes on Cisco IOS devices
ios_user                                             Manage the aggregate of local users on Cisco IOS d...
ios_vlan                                             Manage VLANs on IOS network devices
ios_vrf                                              Manage the collection of VRF definitions on Cisco ...

公式ドキュメントでは、モジュールリストから検索します。

ansible-doc -l のみの場合、モジュールの一覧を表示


■ コマンド

オプションを知りたい

あれするときのオプションは何だったかな?という時に調べる方法です。

$ [特にオプションを付けずにコマンドを実行、または -h オプション]
  • 実行例: ansible-playbook コマンドのヘルプを表示する
$ ansible-playbook -h
Usage: ansible-playbook [options] playbook.yml [playbook2 ...]

Runs Ansible playbooks, executing the defined tasks on the targeted hosts.

Options:
  --ask-vault-pass      ask for vault password
  -C, --check           don't make any changes; instead, try to predict some
                        of the changes that may occur
  -D, --diff            when changing (small) files and templates, show the
                        differences in those files; works great with --check
(...略...)

-h オプションなしで、単に ansible-playbook でも可

公式ドキュメントでは、ansible-playbook コマンド説明ページで確認します。(一覧はこちら


プラグイン

コネクションプラグインの一覧を表示したい

コネクションプラグインsshnetwork_cliなど)ってどんなのがあったかな?という時に調べる方法です。

ansible-doc -t connection -l
  • 実行例
$ ansible-doc -t connection -l
buildah      Interact with an existing buildah container
chroot       Interact with local chroot
docker       Run tasks in docker containers
(...略...)
netconf      Provides a persistent connection using the netconf protocol
network_cli  Use network_cli to run command on network appliances
(...略...)

公式ドキュメントでは、コネクションプラグインのリストを確認します。

コネクションプラグインの詳細を表示したい

コネクションプラグイン名は分かっているけれど、利用される変数名などの詳細を知りたい時に調べる方法です。

ansible-doc -t connection [コネクションプラグイン名]
  • 実行例: netconf コネクションプラグインの詳細を表示する
$ ansible-doc -t connection netconf
> NETCONF    (/home/vagrant/ansible2780/lib/python2.7/site-packages/ansible/plugins/connection/netconf.py)

        This connection plugin provides a connection to remote devices over the SSH
        NETCONF subsystem.  This connection plugin is typically used by network
        devices for sending and receiving RPC calls over NETCONF. Note this connection
        plugin requires ncclient to be installed on the local Ansible controller.

OPTIONS (= is mandatory):

- host
        Specifies the remote device FQDN or IP address to establish the SSH connection
        to.
        [Default: inventory_hostname]
        set_via:
          vars:
          - name: ansible_host
(...略...)

公式ドキュメントでは、netconf コネクションプラグインの説明ページを確認します。


■ 設定

項目名を知りたい

ansible.cfg環境変数で定義する設定項目名を知りたい時に調べる方法です。

ansible-config dump | grep [正規表現]
  • 実行例: timeout が含まれる設定項目名を表示する
$ ansible-config dump | grep -i timeout
CACHE_PLUGIN_TIMEOUT(default) = 86400
DEFAULT_GATHER_TIMEOUT(default) = 10
DEFAULT_TIMEOUT(default) = 10
PERSISTENT_COMMAND_TIMEOUT(default) = 10
PERSISTENT_CONNECT_RETRY_TIMEOUT(default) = 15
PERSISTENT_CONNECT_TIMEOUT(default) = 30

公式ドキュメントでは、設定一覧のページを確認します。


■ fact変数名の一部からfact変数名を特定したい

fact変数名の一部しか分かっていないけれど、どのfact変数かを特定したい時に調べる方法です。

ansible -i [インベントリ] [ターゲット] -m setup -a "filter=[パターン]" 

-m オプションを省略すると、すべてのfact変数の内容が表示されます

  • 実行例: localhost の fact変数で ipv4 が含まれるものを表示
$ ansible -i localhost, all -m setup -a "filter=*ipv4*" -c local
localhost | SUCCESS => {
    "ansible_facts": {
        "ansible_all_ipv4_addresses": [
            "172.17.0.1", 
            "10.0.2.15", 
            "172.16.0.9"
        ], 
        "ansible_default_ipv4": {
            "address": "10.0.2.15", 
            "alias": "eth0", 
            "broadcast": "10.0.2.255", 
            "gateway": "10.0.2.2", 
            "interface": "eth0", 
            "macaddress": "52:54:00:xx:xx:xx", 
            "mtu": 1500, 
            "netmask": "255.255.255.0", 
            "network": "10.0.2.0", 
            "type": "ether"
        }
    }, 
    "changed": false
}


■ まとめ

オフライン状態で、Ansible のモジュールやコネクションプラグイン、設定項目について調べる方法をご紹介しました。個人的には意外と調べる方法方があった、という印象を受けました。

もし、インターネットに接続できないシーンで調べごとをしたいときのめに、参考にしていただければ幸いです。