HowTo Access Inbuilt Help Ansible Using Ansible-doc Command

Ansible is a newer configuration management tool as compared to puppet or chef but has gained immense popularity due to its agent-less architecture and relatively simple to use YAML file based playbooks. Ansible is a modular infrastructure management solution with over 450 modules being shipped with the current release as of this writing. Due to the availability of a large number of modules, remembering how to use each one is relatively difficult and going out to the internet every time to check the syntax and usage of a module seems tedious. It would be extremely helpful if ansible had something similar to the Linux man pages. Ansible actually does have something that partially resembles the Linux man pages. This feature is provided by the ansible-doc command.

In this article, we’ll show you how to efficiently use ansible-doc with the help of some examples.

Version of ansible-doc installed on the system

It’s always useful to know what version of a software you are working with. To view the version of ansible-doc installed on the system, we use the ansible-doc command with the –version option.

[root@arkit-centos ~]# ansible-doc --version
ansible-doc 2.3.0.0
config file = /etc/ansible/ansible.cfg
configured module search path = Default w/o overrides
python version = 2.7.5 (default, Aug 4 2017, 00:39:18) [GCC 4.8.5 20150623 (Red Hat 4.8.5-16)]

Get help on available options

The ansible-doc command provides a number of useful help options. To view the list of available help options, use the ansible-doc command with the -h option as shown below.

[root@arkit-centos ~]# ansible-doc -h
Usage: ansible-doc [options] [module...]

Options:
-a, --all Show documentation for all modules
-h, --help show this help message and exit
-l, --list List available modules
-M MODULE_PATH, --module-path=MODULE_PATH
specify path(s) to module library (default=None)
-s, --snippet Show playbook snippet for specified module(s)
-v, --verbose verbose mode (-vvv for more, -vvvv to enable
connection debugging)
--version show program's version number and exit

In the preceding portion of the article, we will show you how to use some of these options. Note that if you run the ansible-doc command with the -a option to view all documentation about all modules, this command will take a while to show it’s output as a lot of content will be displayed.

List available modules in Ansible Using ansible-doc

To list all the modules that ansible-doc has information on, use the ansible-doc command with the -l option.
Given below a snippet from the output:

[root@arkit-centos ~]# ansible-doc -l
a10_server Manage A10 Networks AX/SoftAX/Thunder/vThunder devices' server object.
a10_server_axapi3 Manage A10 Networks AX/SoftAX/Thunder/vThunder devices
a10_service_group Manage A10 Networks AX/SoftAX/Thunder/vThunder devices' service groups.
a10_virtual_server Manage A10 Networks AX/SoftAX/Thunder/vThunder devices' virtual servers.
accelerate Enable accelerated mode on remote node
acl Sets and retrieves file ACL information.
add_host add a host (and alternatively a group) to the ansible-playbook in-memory inventory
airbrake_deployment Notify airbrake about app deployments

View available actions with the module

Information about the available actions we can use with the module, use the ansible-doc command with the -s option followed by the module name.
In the example given below, we query usage information about the firewalld module:

[root@arkit-centos ~]# ansible-doc -s firewalld

Detailed module usage information with example

This is the one that most closely resembles what we are familiar with seeing on the man page. To view detailed information on how to use a module, use the ansible-doc command followed by the module name. In the below example, we use ansible-doc to print information on how to use the known_hosts module:

[root@arkit-centos ~]# ansible-doc known_hosts

As you might’ve noticed in the above example, a very neat feature of ansible-doc is that it clearly outlines required fields for modules with the equal to(=) symbol thereby making the construction of playbooks using these modules easier.

Conclusion

In this quick article, we showed you how to query the inbuilt documentation on various modules provided with your ansible installation. We hope that you find this information useful and it saves you some time when you are searching for documentation on how to use modules in the future.

Related Articles

Playbook Writing guide

Tower Installation Steps

Password Less Connection Using Playbook

Docs