Updated March 29, 2023
Introduction to Ansible Plugins
Ansible plugins are separately available functions which are used to work with Ansible modules. These are the codes developed to provide additional support to Ansible modules while working on remote target hosts. Though the Ansible package comes with many plugins, we can also write our custom plugins. In Ansible, plugins are prepared in an architecture that adds more flexibility and expandability to the feature set. Most importantly, plugins are different from modules and run only locally on the Ansible controller node within the Ansible process. In addition, plugins provide additional options and extensions to the core functionality of Ansible, like output logging, inventory connection, data transformation.
Working of Ansible Plugins
Ansible plugins work locally on the Ansible controller node, which means some data is given to a plugin, and the plugin processes that data. Modules use this processed data to perform some tasks on remote target machines. This might look easy, but one can easily get puzzled while choosing or using plugins, as the syntax is not in YAML of JSON. Plugins follow a unique syntax which is different for different plugins.
When you have developed a plugin, it must reside in the Ansible default plugin directory under a directory whose name is based on the plugin type. These are /usr/share/ansible/plugins/ and ~/.ansible/plugins/. Under these directories, you can create a directory named as plugin type like lookup, callback, etc., then place plugin file under it. Also, the ANSIBLE_plugin_type_PLUGINSenvironment variable (such as as$ANSIBLE_VARS_PLUGINSand$ANSIBLE_INVENTORY_PLUGINS) can be used to set the location of local plugins. Once your plugins files are located under these locations, then you can use them for any playbook, task, role, or local module. As from these directories, Ansible can load the plugins.
To confirm your plugin is working or loading. You can use ansible-doc to check the plugin, run the command like below:
ansible-doc -t <plugin_type><plugin_name>
In some cases, you might want to use a plugin only for some playbooks or roles; then, you can copy the plugin file under a directory named <plugin_type> under the directory that contains playbook or within that role, respectively. Also, the easiest way to get a plugin is to copy it from another location or source and use it in your environment; similarly, you can share your plugins. This works the same way as modules. Plugins are embedded in roles for sharing.
Ansible package is shipped with a range of plugins, including Action, Callback, Cache, Become, Connection, Inventory, Lookup, Shell, Vars, Filters, Test. Also, you can add your customized plugins by writing the incompatible version of Python, and code should have error reporting, return strings in Unicode, and line with Ansible documentation and configuration standards. In the next section, we will learn about some of the default plugins types with examples.
List of Ansible Plugins
Below is a list of plugins types provided by Ansible packages, but you must note that this list if not exhaustive and can be extended in future releases or updated in the current release. In addition, these plugin types further have plugins that can use in our playbooks. For the latest list of plugin types, you can refer below the official Ansible community page.
https://docs.ansible.com/ansible/latest/plugins/plugins.html
To get a list of available plugin’s list of a plugin type, you can use the below command:
ansible-doc -t <plugin_type> -l
Also, for practical purposes, here we have an Ansible control server named ansible-controller and two remotes hosts named host-one and host-two. We will create playbooks, run Ansible commands on the ansible-controller node, and see the results on remote hosts. The way of use in these examples is completely to show you how to use these, but your real-life usage/requirements may be different from these.
1. Action
These plugins work on the front end and are executed in the local controller node before calling any module. These plugins are associated with some modules and are executed by default when such modules are used. Therefore, you cannot list action plugins.
2. Become
These plugins are enabled by default, and these are used to ensure that Ansible can use certain privileges on remote machines while running such commands, which need higher privileges. Plugin list includes sudo, su, doas, runas. These plugins are used along with become_methodkeyword in a playbook. For example, we have a playbook with content like below, here we are running this playbook with the root user, but as we mentioned becomes parameters in the playbook. We are trying to run the command as ec2-user. In the output, we will see that command ran as ec2-user.
Please note, this user must exist on the target machine, else the playbook will fail.
---
- hosts: all
become: yes
become_user: ec2-user
become_method: sudo
tasks:
- name: here we are chekcing the user id by which command is running.
shell: id
register: id_var
- debug:
var: id_var['stdout_lines']
Running this playbook like below:
ansible-playbook ansible_sudo.yaml
We get the output like below:
3. Lookup
These plugins are used to fetch data from an external source. This uses Jinja2. One of the important plugins is the file which is used to read the contents of a file. For example, we will take contents from a local file on the Ansible control machine and display its output using a plugin file which is a lookup plugin type. For this, we create a playbook, like below:
---
- hosts: localhost
tasks:
- name: here we will display contents of /tmp/samplefile
debug:
msg: These are the contents of /tmp/samplefile - {{lookup('file', '/tmp/samplefile')}}
Code:
ansible-playbook ansible_lookup_file.yaml
We get output like below:
4. Vars
These plugins provided additional data to Ansible plays which inventory, playbook, and parameters provided on the command line did not provide. These plugins are automatically enabled and used with keywords like host_vars and group_vars.
5. Cache
These plugins are used to store a cache of Ansible facts so that we do not have to gather those, again and again; this can be helpful in cost-saving where I/O is measured and incur costs.
6. Filters
These allow you to filter data within the controller node and provide it to playbooks and templates. This uses Jinja2. In this type, the variety of plugins is vast also; there are some mathematics-related plugins like abs, int, pow, root. To check some of these, we can make a playbook with content like below: –
---
- hosts: localhost
vars:
var_one: -2.5
tasks:
- set_fact:
var_abs: "{{ var_one | abs }}"
var_pow: "{{ var_one | pow(5) }}"
- debug:
msg: Absolute value -2.5 is "{{ var_abs }}"
- debug:
msg: Fifth power of -2.5 is "{{ var_pow }}"
Code:
ansible-playbook filter_math.yaml
The output will be like below:
Conclusion
As we saw in this article, Ansible plugins can perform a vital part in Ansible playbooks, especially when we have needs like data transformation, filtering, etc. You must have good knowledge of using the plugins if you have multiple environments and your needs are to process data locally on the controller node. So learn it first and then use it.
Recommended Articles
This is a guide to Ansible Plugins. Here we discuss the Working and the list of plugins types provided by Ansible packages. You may also have a look at the following articles to learn more –
