How to use the command 'ansible-doc' (with examples)
The ‘ansible-doc’ command is a useful tool in Ansible that allows you to access documentation on modules and plugins installed in Ansible libraries. It provides information and details about the available plugins and their usage, allowing you to easily find the necessary information when working on your Ansible playbooks.
Use case 1: List available action plugins (modules)
Code:
ansible-doc --list
Motivation: This use case is useful when you want to see a comprehensive list of action plugins (modules) available in Ansible. It allows you to quickly browse through the available modules and choose the appropriate one for your use case.
Explanation: The ‘–list’ argument is used with the ‘ansible-doc’ command to list all the available action plugins (modules). This command will display a list of action plugins along with their short descriptions.
Example output:
ansible.builtin.apt Manage apt packages
ansible.builtin.service Manage services
ansible.builtin.copy Copy files to remote locations
...
Use case 2: List available plugins of a specific type
Code:
ansible-doc --type become --list
Motivation: This use case is helpful when you want to list all the plugins of a specific type. For example, if you want to explore all the ‘become’ plugins in Ansible, you can use this command to get a list of available ‘become’ plugins.
Explanation: The ‘–type’ argument is used to specify the type of plugins you want to list. In this example, we’re using ‘–type become’ to list all the ‘become’ plugins. The ‘–list’ argument is used to display a terse listing of the plugins and their short descriptions.
Example output:
ansible.builtin.become Run operations with become
ansible.collection.system.windows.become Run operations with become on Windows targets
Use case 3: Show information about a specific action plugin (module)
Code:
ansible-doc apt
Motivation: This use case is handy when you need detailed information about a specific action plugin (module). It provides a comprehensive explanation and usage details of the chosen plugin.
Explanation: The ‘ansible-doc’ command followed by the plugin name is used to show information about a specific action plugin. In this example, we’re using the ‘apt’ plugin as an argument. The command will display detailed information about the ‘apt’ action plugin.
Example output:
APT (short for Advanced Package Tool) is a package management system used by Debian-based distributions, like Ubuntu. The APT module allows you to install, remove, upgrade, and manage packages using apt.
Example Usage:
- name: Install package using apt
apt:
name: package_name
Use case 4: Show information about a plugin with a specific type
Code:
ansible-doc --type connection ssh
Motivation: This use case is useful when you want to get information about a plugin of a specific type. For example, if you want to explore the ‘ssh’ connection plugin in Ansible, you can use this command to obtain detailed information about it.
Explanation: The ‘–type’ argument is used to specify the plugin type, and the plugin name is passed as an argument to the ‘ansible-doc’ command. In this example, we’re using the ‘–type connection’ to specify the plugin type as ‘connection’, and ‘ssh’ as the plugin name. The command will display detailed information about the ‘ssh’ connection plugin.
Example output:
SSH is a secure network protocol that allows secure remote command-line login, remote command execution, and other secure network services between two networked computers. The SSH connection plugin allows you to establish SSH connections to remote hosts and manage them using Ansible.
Example Configuration:
ansible_connection: ssh
ansible_host: remote_host
ansible_user: username
ansible_password: password
ansible_become: True
Use case 5: Show the playbook snippet for an action plugin (module)
Code:
ansible-doc --snippet apt
Motivation: This use case is helpful when you want to quickly see a playbook snippet for a specific action plugin. It provides a concise example that you can directly use in your playbook.
Explanation: The ‘–snippet’ argument is used with the ‘ansible-doc’ command to show the playbook snippet for a specific action plugin. In this example, we’re using the ‘apt’ plugin to display the playbook snippet. The command will display a playbook snippet that showcases the usage of the ‘apt’ action plugin.
Example output:
# Example playbook snippet for apt
- name: Install package using apt
apt:
name: package_name
Use case 6: Show information about an action plugin (module) as JSON
Code:
ansible-doc --json apt
Motivation: This use case is handy when you want to get information about a specific action plugin (module) in JSON format. JSON format allows easy parsing and integration with other tools or scripts.
Explanation: The ‘–json’ argument is used with the ‘ansible-doc’ command to show the information about a specific action plugin in JSON format. In this example, we’re using the ‘apt’ plugin to display information in JSON format. The command will display detailed information about the ‘apt’ action plugin in JSON format.
Example output:
{
"filename": "apt.py",
"author": "Ansible Core Team",
"min_ansible_version": "2.9",
"short_description": "Manage apt packages",
"description": "APT (short for Advanced Package Tool) is a package management system used by Debian-based distributions, like Ubuntu. The APT module allows you to install, remove, upgrade, and manage packages using apt.",
"options": [
{
"name": {
"required": true,
"description": "The name of the package to install, remove, or upgrade.",
"default": null,
"choices": null
},
...
]
},
...
]
}
Conclusion:
The ‘ansible-doc’ command is a powerful tool in Ansible that provides easy access to module and plugin documentation. Its various use cases allow users to explore the available plugins, view details of specific plugins, and obtain playbook snippets for quick reference. This command helps streamline the development process and improve productivity when working with Ansible playbooks.
