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 126.96.36.199 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.
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.