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.
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
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 18.104.22.168 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
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.
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.
Latest posts by Sahil Suri (see all)
- git: What is detached HEAD state? - June 12, 2018
- git checkout command explained - June 11, 2018
- Using HEAD and git commit hash to differentiate between committed file versions - June 8, 2018
- git log command explained with examples - June 7, 2018
- git add command explained with examples - June 6, 2018