Updated April 14, 2023
Introduction to ansible-doc
Ansible-doc is a tool provided by the core Ansible package which contains all the documentation related to modules and plugins installed in Ansible libraries. This works as a command on the command line prompt. This tool/command can guide you by providing documentation on plugins and modules, their use, a short description, available parameters and related options. Adding to this, Ansible-doc provides example snippets for most of the available modules and plugins, which can directly be used in playbooks. Also, for customized or self-created non-default modules, when we have to provide related information via documentation, Ansible-doc is set to be used to read that documentation from libraries.
Syntax & Parameters
Ansible-doc works as a Linux/Unix command. There are certain parameters and related acceptable as well as default options. Below are some of those parameters if not all. One must remember these when using Ansible-doc. Also point to note that if you are not aware of how to use it or forgot it at some moment, just remember to run below to get details about this command-line tool.
Syntax:
ansible-doc -h
Or
ansible-doc ---help
For syntax, we have to provide the concerned module name to get all related documentation. Like below: –
ansible-doc <module name>
Similarly, for plugins we have to use like below to get details of a plugin: –
ansible-doc –type <plugin type>
Below is the list of available parameters and related available options.
- “-v ” or “–version”: To display the version of installed Ansible
- “-F” or “list_files”: To show plugin’s name and their related source
- “-M” or “—module_path”: To specify module library path, if multiple, separate then with Default is ‘~/.ansible/plugins/modules:/usr/share/ansible/plugins/modules’.
- “-j” or “–json”: To display the output in JSON
- “-l” or “–list”: To display the list of available
- “-s” or “snippet”: For specified plugins display the playbook
- “t” or “type”: To choose the plugin type; default is a module; The available plugins are vars, strategy, module, shell, netconf, lookup, inventory, httpapi, connection, cliconf, callback, cache, become.
Working of ansible-doc
Ansible module is a command-line tool, which works just as another command on Linux. While we are creating a playbook and unsure about any module or plugin, then we shall use ansible-doc to read the documentation of related plugin or module. This makes us understand the insights of a plugin or module and related possibilities to use the same.
Also while working with ansible-doc, one must know below points:
- ANSIBLE-CONFIG variable is defined to overrides the default configuration
- For default configuration /etc/ansible/ansible.cfg or ~/.ansible.cfg files will be
- The environment should be properly configured to work with Ansible-doc.
- There are man pages and info pages for Ansible-doc command which can be referred for
- When you are creating a custom module then DOCUMENTATION part is an important aspect and have syntax like below:
DOCUMENTATION = '''
---
module: sample_module short_description: Description of module # ... continue below with other fields ... '''
Examples of ansible-doc
In this section, we will see some practical examples of working with ansible-doc and how to use it in real environment. For this, we have a lab setup where we have our Ansible controller node from where we run playbooks or Ansible commands. The command-line tool ansible-doc will not be running on remote target machines but we will be using it on Ansible Controller node only as this is a tool to provide documentation and not to perform any changes on remote hosts.
Example #1
In this example, we will see how to get documentation for the Ansible module copy. For this, we will run below command and see the output.
Command:
ansible-doc copy
In the output, where we can see below: –
- Description
- Parameters
- Available options and default
Output:
- Notes
- Online
- Author
Examples
Return values
Example #2
In this example, we will see how to get details/documentation of plugins. The plugin list includes vars, strategy, module, shell, netconf, lookup, inventory, httpapi, connection, cliconf, callback, cache, become plugins. We will run a command like below to check for connection plugin usage:
Command:
ansible-doc -t connection -l
The output looks like below, here we can see the available features under this plugin:
Output:
Now to show the ssh plugin usage and more details, we can run a command like below:
Command:
ansible-doc -t connection -s ssh
Output:
Example #3
In this example, we will see only available parameters for a module. This is different as here we only see small details and not other information like reference, examples, etc. For this, we are using “-s” which stands for the snippet. Here we are checking the outpour of the Ansible reboot module.
Command:
ansible-doc -s reboot
In the output, we can see that only parameters are shown with small details:
Output:
Example #4
Now for some reason, if you want to see the output in JSON format, then you can use the option “-j” to do this. Like in the below command, we are seeing the format in JSON format.
Command:
ansible-doc fetch -j
Output:
Example #5
In this example, we will check the installed Ansible package configuration on the controller system using ansible-doc. For this we have a command like below:
Command:
ansible-doc --version
The output is like below, where we can see the installed Ansible version, configuration file, module search path, python module location, Executable location for python, and python version.
Output:
Example #6
In this example, we can see the way to list all the modules available. For this, we use the parameter “-l”.
Command:
ansible-doc -l
Output:
Also, we can use “-F” parameter to get all the modules with source file location:
Command:
ansible-doc -F
Output:
Conclusion
As we saw in this article, ansible-doc is a very useful tool to understand the Ansible’s know-how and what- is. This tool helps you when you are working in an offline environment and have no other references available. So having good knowledge on how to search for information using Ansible-doc makes you self- reliant. So learn it first and then use it.
Recommended Article
This is a guide to ansible-doc. Here we discuss the introduction of ansible-doc and its syntax and parameters along with examples and different commands. You can also go through our other suggested articles to learn more –
