As this chapter is all about modules and how to create them, let's recap how to use modules. We've done this throughout this book, but we have not drawn attention to some of the specifics related to how they work. One of the key things we have not discussed is how the Ansible engine talks to its modules and vice versa, so let's explore this now.

As ever, when working with Ansible commands, we need an inventory to run our commands against. For this chapter, as our focus is on the modules themselves, we will use a very simple and small inventory, as shown here:

[frontends]
frt01.example.com

[appservers]
app01.example.com

Now, for the first part of our recap, you can run a module very easily via an ad hoc command and use the -m switch to tell Ansible which module you want to run. Hence, one of the simplest commands you can run is the Ansible ping command, as shown here:

$ ansible -i hosts appservers -m ping

Now, one thing we have not previously looked at is the communication between Ansible and its modules; however, let's examine the output of the preceding command:

$ ansible -i hosts appservers -m ping
app01.example.com | SUCCESS => {
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python"
    },
    "changed": false,
    "ping": "pong"
}

Did you notice the structure of the output – the curly braces, colons, and commas? Yes, Ansible uses JSON-formatted data to talk to its modules, and the modules report their data back to Ansible in JSON as well. The preceding output is, in fact, a subset of the JSON-formatted data returned to the Ansible engine by the ping module.

Of course, we never have to worry about this as we work with the modules using either key=value pairs on the command line or YAML in playbooks and roles. Hence, the JSON is shielded from us, but this is an important fact to bear in mind as we head into the world of module development later in this chapter.

Ansible modules are just like functions in a high-level programming language, in that they take a well-defined list of arguments as input, perform their function, and then provide a set of output data, which is also well-defined and documented. We'll look at this in more detail later in this chapter. Of course, the preceding command didn't include any arguments, so this was the simplest possible invocation of a module via Ansible.

Now, let's run another command that takes an argument and passes that data to the module:

$ ansible -i hosts appservers -m command -a "/bin/echo 'hello modules'"

In this case, we provided a single string as an argument to the command module, which Ansible, in turn, converts into JSON and passes down to the command module when it's invoked. When you run this ad hoc command, you will see an output similar to the following:

$  ansible -i hosts appservers -m command -a "/bin/echo 'hello modules'"
app01.example.com | CHANGED | rc=0 >>
hello modules

In this instance, the output data does not appear to be JSON formatted; however, what Ansible prints to the Terminal when you run a module is only a subset of the data that each module returns – for example, both the CHANGED status and rc=0 exit code from our command were passed back to Ansible in a JSON-formatted data structure – this was just hidden from us.

This point doesn't need to be labored too much, but it is important to set a context. It is this context that we shall build upon throughout this chapter, so simply remember these key points:

• Communication between Ansible and its modules is done through JSON-formatted data structures.
• Modules take input data that controls how they function (arguments).
• Modules always return data – at the very least, the status of the module's execution (for example, changed, ok, or failed).

Of course, before you start coding your own modules, it makes sense to check whether a module that can perform all (or some) of the functionality you need already exists. We will explore this in the next section.