Creating and Consuming Plugins

Modules have been a very obvious and key part of our journey through Ansible so far. They are used to execute well-defined tasks and can be used either in one-off commands (using ad hoc commands) or as part of a much larger playbook. Plugins are just as important to Ansible, and we have used them in all of our testing so far without even realizing it! While modules are always used to create some kind of task in Ansible, the way that plugins are used depends on their use case. There are many different types of plugins; we will introduce them to you in this chapter and give you an idea of their purpose. But, as a tester, did you realize that when Ansible connects to a remote server using SSH, functionality is provided by a connection plugin? This demonstrates the important role that plugins play.

In this chapter, we will provide you with an in-depth introduction to plugins, as well as show you how to explore the various plugins that come with Ansible...

Technical requirements

This chapter assumes that you have set up your control host with Ansible, as detailed in Chapter 1, Getting Started with Ansible, and that you are using the most recent version available. The examples in this chapter have been tested with ansible-core version 2.15. This chapter also assumes that you have at least one additional host to test against; ideally, this should be Linux-based.

Although we will give specific examples of hostnames in this chapter, you are free to substitute them with your own hostname and/or IP addresses, and details of how to do this are provided at the appropriate places. The plugin development work covered in this chapter assumes the presence of a Python 3 development environment on your computer, and that you are running either Linux, FreeBSD, or macOS. Where additional Python modules are needed, their installation is documented. The task of building module documentation has some very specific requirements in Python 3.10 or later...

Discovering the plugin types

Ansible’s code has always been designed to be modular—indeed, this is one of its core strengths. Whether that is through the use of modules to perform tasks or through plugins (as we will see shortly), Ansible’s modular design allows it to be as versatile and powerful as it has demonstrated itself to be so far in this book. As with modules, Ansible plugins are all written in Python and are expected to ingest and return data in a certain well-defined format (more on this later). Ansible’s plugins are often invisible in their function in that you rarely call them by name in your commands or playbooks, yet they are responsible for some of the most important features Ansible has to offer, including SSH connectivity, the ability to parse inventory files (in INI format, YAML, or otherwise), and the ability to run jinja2 filters on your data.

As ever, let’s validate the presence of a suitably installed version of Ansible on...

Finding included plugins

As we discussed in the preceding section, plugins are not as apparent in Ansible as their module counterparts are, and yet we have been using them behind the scenes in every single Ansible command we’ve issued so far! Let’s build on our work in the previous section, where we looked at the plugin documentation, by looking at where we can find the source code for the plugins. This, in turn, will serve as a precursor to us building a simple plugin of our own.

If you installed Ansible on a Linux system using a package manager (that is, via an RPM or DEB package), then the location of your plugins will depend on your OS. For example, on my test CentOS 8 system where I installed Ansible from the official RPM package, I can see the plugins installed here:

$ ls /usr/lib/python3.11/site-packages/ansible/plugins/
action cliconf httpapi inventory lookup terminal
become connection __init__.py loader.py netconf test
cache doc_fragments __init__.pyc loader...

Creating custom plugins

In this section, we will take you through a practical guide to creating a plugin. The example will be, by necessity, simple. However, hopefully, it will serve you well in guiding you in the principles and best practices of plugin development and give you a solid foundation to build more complex plugins. We will even show you how to integrate these with your playbooks and, when you’re ready, submit them to the official Ansible project for inclusion.

As we noted when we built a module, Ansible is written in Python, and its plugins are no exception. As a result, you will need to write your plugin in Python; so, to get started on developing a plugin, you will need to make sure you have Python and a few essential tools installed. If you already have Ansible running on your development machine, you probably have the required packages installed.

Let’s get started with creating a plugin. Although there are many similarities between coding modules...

Sharing plugins with the community

You may wish to submit your new plugin to the Ansible project, just as we considered for our custom modules in Chapter 5, Creating and Consuming Modules. The process for doing this with plugins is almost identical to what you do for modules, which this section will recap.

Note

Using the following process will submit a real request to the Ansible project on GitHub to merge the code you submit with their code. Do not follow this process unless you genuinely have a new module that is ready to be submitted to the Ansible code base.

To submit your plugin as a PR of the Ansible repository, you need to fork the devel branch of the official Ansible repository. To do this, log in to your GitHub account on your web browser (or create an account if you don’t already have one), and then navigate to https://github.com/ansible/ansible.git. Click on Fork at the top-right corner of the page:



Figure 7.3 – Ansible GitHub repository...

Summary

Ansible plugins are a core part of Ansible’s functionality and as we discovered in this chapter, we have been working with them throughout this book without even realizing it! Ansible’s modular design makes it easy to extend and add functionality, regardless of whether you are working with modules or the various types of plugins that are currently supported. Whether it’s to add a new filter for string processing or a new way of looking up data (or perhaps even a new connection mechanism to new technology), Ansible plugins provide a complete framework that can extend Ansible far beyond its already extensive capabilities.

In this chapter, we learned about the various types of plugins that are supported by Ansible, before exploring them in greater detail and looking at we you can obtain documentation and information on the existing ones. We then completed two practical examples to create two different types of plugins for Ansible while looking at the best...

Questions

Answer the following questions to test your knowledge of this chapter:

1. Which of the following ansible-doc commands can you use to list the names of all the cache plugins?
   1. ansible-doc -a cache -l
   2. ansible-doc cache -l
   3. ansible-doc -a cache
   4. ansible-doc -t cache -l
   5. ansible-doc cache
2. Which class do you need to add to your lookup plugin’s code to include the bulk of the plugin code, including run(), the items loop, try, and except?
   1. LookupModule
   2. RunModule
   3. StartModule
   4. InitModule
   5. LoadModule
3. True or false: To create custom plugins with complex operations rather than printing simple hello world text using Python, you need to install Python with the relevant dependencies on your OS.
   1. True
   2. False

Further reading

You can find all of the plugins on Ansible by accessing the Ansible repository directly at https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins.