Right the First Time

Tip 4: YAML

If you have followed the guidelines of this article up to this point, you are already using a folder structure that can cope with the demands of everyday life. It would be a pity to ruin it with a muddle of playbooks and self-written roles. Oddly enough, many Ansible administrators fall into this very trap. Instead of sticking to either Ansible-native syntax,

- name: add user testuser1
  user: name=testuser1 state=present groups=wheel

or YAML syntax,

- name: add user linuxmagazin
  user:
    name: testuser1
    state: present
    groups: wheel

admins wildly mix steps in both notations in their playbooks.

Of course, that can happen if time is tight and you just copy and paste the solution to an urgent problem off the web. A mix of both styles can be found in many places, even in the same files, but it is obviously not ideal: It makes sense to choose one syntax. Ideally, you will want to opt for YAML because it improves the structure of the Ansible statements and adds clarity.

Tip 5: Variables

Most admins will be aware of the case in which an Ansible playbook written years ago by an employee who has long since left the company needs an update. The developer made extensive use of variables at the time. It's just a pity that they didn't document them, because that would mean their successor would understand that the variable mgmt_cws1_n7p1 refers the first port on the first network card in the first cluster workstation (aka jump host) of the management network. With good documentation, the new admin might even understand that the count takes the names of the system's network cards and, therefore, the counterpart to n7p1 on the workstation is ens7f0 – not that there are seven network cards in the computer.

Coulda, woulda, shoulda. The reality of most Ansible setups in the wild tends to be that variables, and especially their names, are completely undocumented. This is a huge problem and generates totally unnecessary potential for trouble. Every author of Ansible statements is therefore strongly advised to define variables centrally, as described, and to assign meaningful default values. Additionally, they should add a short explanation in each case, unless the type and function of the variable is absolutely and reliably self-evident.

The hurdles for the latter criterion are high. Even a root_pw variable offers only limited scope for drawing conclusions on its function without reading the Ansible source code. Is it the root password for a system, a container, or the password for root in MariaDB? Questions and more questions arise to which the Ansible admin would do better to provide the answers in the form of comments instead of leaving gaps.

Tip 6: Hand-in-Hand

In some places, administrators develop Ansible statements in the firm belief that no one else in the organization will ever be forced to call Ansible anyway. Then off they go on a skiing vacation, have a serious accident, go on sabbatical, or find themselves involved in some other event that leads to being away for weeks. Ultimately, you end up with some hapless employee sitting in front of the installation tasked with making a "minor adjustment" because a problem occurred in production.

If you want to make sure that, say, variables in your playbooks are not assigned invalid values, then you would ideally introduce tests. The emphasis here is on "invalid." Things that are syntactically correct for Ansible will not necessarily work as values for a variable in a service configuration file.

The function for checking the content of variables is assert; Listing 1 shows an example. If the version variable does not contain a number greater than  , the assert statement causes Ansible to abort. Ideally, of course, a directive like this should be in the code before moving on to further tasks, such as rolling out a configuration file.

- name: "Validate version is a number, > 0"
  assert:
    that:
      - "{{ version | int }} > 0"
    msg: "'version' must be a number and > 0, is \"{{version}}\""