Introduction

In our earlier articles on Ansible we introduced you to some basic concepts related to Ansible and explained how to install it and set up a basic environment to use. In a subsequent article, we explained the basics of the YAML markup language to help you understand playbook structure. In this article, we’ll focus on how to access and make the best use of Ansible documentation. If you search for documentation on Ansible modules online, you’ll find a number of places where thorough information about the modules is available. For the purpose of this post, we’ll be looking at the Ansible documentation that is available bundled with the distribution. We’ll show you how to list the modules that get installed when we install Ansible and also how to view more detailed information about a module.

 

Ansible-doc

To view documentation on Ansible modules, we use a command called ansible-doc. If you need to check the command line options available with the ansible-doc command, then you may simply type

man ansible-doc

Given below is a snippet from the man page showing the available options:

--version
show program's version number and exit

-M, --module-path
prepend colon-separated path(s) to module library (default=[u'/home/jenkins/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])

-a, --all
For internal testing only Show documentation for all plugins.

-h, --help
show this help message and exit

-l, --list
List available plugins

-s, --snippet
Show playbook snippet for specified plugin(s)

-t TYPE, --type TYPE
Choose which plugin type (defaults to "module")

-v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)

We will be covering most of these options with examples in this article.

 

Check ansible-doc version:
Before covering the options we use for obtaining information on modules, let’s first check the version of ansible-doc installed on the system.

[sahil@linuxnix:~] $ ansible-doc --version
ansible-doc 2.4.2.0
config file = /etc/ansible/ansible.cfg
configured module search path = [u'/export/home/sahil/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
ansible python module location = /usr/lib/python2.6/site-packages/ansible
executable location = /usr/bin/ansible-doc
python version = 2.6.6 (r266:84292, Aug 9 2016, 06:11:56) [GCC 4.4.7 20120313 (Red Hat 4.4.7-17)]
[sahil@linuxnix:~] $

List installed modules:
Now that we know the version of ansible-doc installed on the system, let’s list the modules available with our ansible distribution. For this, we use the ansible-doc command with the -l option. Here’s a snippet from the output.

[sahil@linuxnix:~] $ 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
aci_aep Manage attachable Access Entity Profile (AEP) on Cisco ACI fabrics (infra:AttEntityP)
aci_ap Manage top level Application Profile (AP) objects on Cisco ACI fabrics (fv:Ap)
aci_bd Manage Bridge Domains (BD) on Cisco ACI Fabrics (fv:BD)
aci_bd_subnet Manage Subnets on Cisco ACI fabrics (fv:Subnet)

This command takes a while to execute so some patience is advised. The output is paginated which allows browsing through the list of modules easier.  Also, we could use the forward slash followed by a keyword to search for a module from within the output.

View options available with a module:
We may use the ansible-doc command with the -s option followed by a module name to view the options/parameters that we could use with the specific module. Given below is an example of using this with the dnf module.

[sahil@linuxnix:~] $ ansible-doc -s dnf
- name: Manages packages with the `dnf' package manager
dnf:
autoremove: # If `yes', removes all "leaf" packages from the system that were originally installed as dependencies
of user-installed packages but which are no longer required by any
such package. Should be used alone or when state is `absent'
conf_file: # The remote dnf configuration file to use for the transaction.
disable_gpg_check: # Whether to disable the GPG checking of signatures of packages being installed. Has an effect only if
state is `present' or `latest'.
disablerepo: # `Repoid' of repositories to disable for the install/update operation. These repos will not persist
beyond the transaction. When specifying multiple repos, separate them
with a ",".
enablerepo: # `Repoid' of repositories to enable for the install/update operation. These repos will not persist
beyond the transaction. When specifying multiple repos, separate them
with a ",".
installroot: # Specifies an alternative installroot, relative to which all packages will be installed.
list: # Various (non-idempotent) commands for usage with `/usr/bin/ansible' and `not' playbooks. See
examples.
name: # (required) Package name, or package specifier with version, like `name-1.0'. When using
state=latest, this can be '*' which means run: dnf -y update. You can also pass a url or a local path to a rpm file.
state: # Whether to install (`present', `latest'), or remove (`absent') a package.

DNF is a package manager for managing software packages on Linux distributions. From the output, we can ascertain information about the parameters/options we are allowed to use while working with the module. Also, notice that the ‘name’ parameter has ‘required’ written against it which indicates that this parameter is not optional while working with the module.

View detailed information about a module:
Using the -s option provides the list of parameters available for use with a module and some summary information about their intended purpose. If you would like to view more verbose information then you should use the ansible-doc command followed by the module name without any options in between. For example, to view detailed information on using the dnf module type the following command

ansible-doc dnf

This will display information about the parameters and options available for use with the module along with the acceptable values for these parameters and effect of setting a parameter to a given value. Any requirements or dependencies of a module will be mentioned. Also, some common usage examples for the module will also be provided. Here is a snippet from the example section when I executed the ‘ansible-doc dnf’ command

EXAMPLES:
- name: install the latest version of Apache
dnf:
name: httpd
state: latest

- name: remove the Apache package
dnf:
name: httpd
state: absent

- name: install the latest version of Apache from the testing repo
dnf:
name: httpd
enablerepo: testing
state: present

As you may observe, the examples are very simple to comprehend and in most cases can be directly ported into Ansible playbooks after modifying the name parameter to the required value. This closely resembles man pages which are available for most UNIX/Linux commands and provide detailed information about these commands along with available options and usage examples.

 

Conclusion

In this article, we explained how we could use the ansible-doc command to access documentation on how to use modules shipped with the ansible distribution. We hope that you’ve found this article to be useful and we look forward towards your feedback.

Post Views: 36,914
The following two tabs change content below.

Sahil Suri

He started his career in IT in 2011 as a system administrator. He has since worked with HP-UX, Solaris and Linux operating systems along with exposure to high availability and virtualization solutions. He has a keen interest in shell, Python and Perl scripting and is learning the ropes on AWS cloud, DevOps tools, and methodologies. He enjoys sharing the knowledge he's gained over the years with the rest of the community.