Right the First Time

In the open source community, people say that Red Hat has a lucky hand when it comes to acquiring other organizations. Many of the acquisitions have since gone on to enjoy an extremely successful existence, including Ceph and Qumranet, the company that launched KVM. Another example of Red Hat's prowess in their shopping sprees is undoubtedly Ansible, which to this day is considered a lean and easy-to-use but still highly efficient automation tool.

If you don't like Puppet, Salt, or even Chef, with their complicated syntaxes, you can enjoy true automation with Ansible – and in a format that almost rivals the simplicity of shell scripts. Some people might need a while to get used to the YAML format, but once the few essential basics are in place, Ansible offers almost boundless automation fun for the whole (operating system) family.

People who eventually become truly adept at Ansible far too often adopt quirks from their own training days that make Ansible inefficient, more complex, or just more difficult to use than it really needs to be. The program's simple controls are, in fact, its undoing. Some admins too often believe that they already know everything about Ansible and – following this logic – stop acquiring further skills. In many companies, this means that large parts of the functionality of the automation system – and thus a large part of its really great feature set – are practically idle.

I want to help you put a stop to that. In this article I reveal how to make sense of your playbooks, what rules to follow, and how to get more out of Ansible than might seem possible in standard use. Although just a few pages are not enough to explain all the special features in Ansible and show all the best practices, the available space is certainly enough to give you food for thought for your own journeys of exploration, so I'll start with a parade of the 10 best tricks for Ansible.

Tip 1: Order

Ansible offers various notation options and can optionally bundle playbooks and roles into individual files or into a complex folder structure. The appeal of managing the entire installation for Ansible in a single file is huge – after all, it saves you having to browse several directories when making changes. The fact that this approach also has disadvantages is often overlooked, until you find yourself sitting in front of a playbook with thousands of lines and unable to see the forest for the trees. The first tip is therefore quite clear: Integrate your Ansible infrastructure into a directory with a meaningful organizational structure. This step also helps you maintain and develop individual parts of the setup independent of each other.

The basic structure to be followed turns out to be very simple. Inside a new ansible/ folder, first create the roles/, group_vars/, and host_vars/ folders. The names tell you what these folders do. DIY Ansible roles end up in roles/, whereas the respective group- and host-specific variables of the setup are stored in group_vars/ and host_vars/. The next step is to create a hosts file where you make a list (in CFG file syntax) of all the hosts that belong to the Ansible setup.

Finally, you need a playbook, which you can name something like users.yml. Ideally, the playbook itself should not contain any immediate steps to be performed on the hosts. In exceptional cases, this principle can be ignored for a single command or a task. However, for the sake of clarity, it is better to create separate roles for the individual tasks in the roles/ folder and then reference them with the roles: directive in users.yml.

The directory structure in the folders with the roles also plays a part. You need at least the tasks/ folder with a main.yml file containing all the steps to be completed. If you have many steps of different types, they can also be stored in arbitrarily named files, which you then include in main.yml with an include statement.

If you need triggers for events on the system after completing certain steps, make a note of them in handlers/main.yml, then define the default values for variables in defaults/main.yml. Templates belong in the templates/ folder. Files that only need to be copied to a system are located in the files/ folder.

All of the arrangements have been made now. The folder structure described above lets you modify individual roles for specific tasks independent of each other and keeps the Ansible web tidy (Figure 1). Additionally, checking the resulting folder structure into a Git directory is highly recommended so it is easier to track changes after the event.

Figure 1: Tidiness is half the battle: The folder structure and file partitioning help you use Ansible in a meaningful way. © Martin Loschwitz

Tip 2: Names

A fad for many Ansible admins is to omit the name parameter when writing Ansible statements, perhaps as a way to avoid typing or because of a belief that names are not absolutely necessary for individual instructions.

Although it is true that names are not required – a block of statements that does not have a defined name will reliably produce the desired result in Ansible – if something does not work, Ansible admins who use name are far better off than those who leave it out. If you do not use names anywhere, the output produced by Ansible in the log is practically meaningless. At the very least, it is far more difficult to interpret it correctly than it actually needs to be.

Giving each statement a meaningful descriptive name in Ansible makes debugging easier and also helps you create documentation as a side effect. Any sysadmin who has weathered an IT storm can imagine how an administrator feels when they open a file containing dozens of anonymous Ansible statements without comments.

However, this point is in no way to be understood as a plea against variables – quite the contrary. Separating code and configuration in Ansible to the extent possible has been proven practical. The roles and playbooks then only use (ideally, sensibly named) variables that are then defined for each individual host in their specific variables.

Tip 3: Logging

Ansible comes with a default logger for the command line. Although it basically works well, it is sometimes a bit chatty. Especially after running many Ansible statements, the terminal window looks more like modern art (Figure 2). An Ansible error could even scroll so far off the screen that it does not even appear in the terminal buffer and is lost forever to your eyes.

Figure 2: This type of Ansible output is probably familiar to most administrators – color and whitespace, but all told, very little information. © Pierre Baillet

What many Ansible users don't realize is that just as Ansible can be extended by new functions with library, it can also be extended with new output modules for the shell. The developer of the Stdout Compact Logger [1] for Ansible took advantage of precisely this ability. It is best to keep this output module inside your Ansible folder (e.g., in the callbacks/ subfolder). In the Ansible configuration (ansible.cfg), you then need to extend the callback_plugins parameter to point to the folder where the additional modules are located.

In this specific case, you also need to set the stdout_callback parameter to anstomlog in the Ansible configuration file. The next call to Ansible brings up a far more compact log that wastes less space on the desktop, while giving you far more information (Figure 3). The plugin adds a timestamp for each message, making it easier to track temporal events.

Figure 3: Instead of showing you a mostly blank screen, the Compact Logger comes up with comparatively useful output enriched with many details. © Pierre Baillet