YAML best practices for Ansible playbooks - tasks

This post is a follow-up to a recent discussion about YAML formatting for complex Ansible playbook tasks on the Ansible Project mailing list, and will also be appearing as part of Appendix B: Ansible Best Practices and Conventions in my Ansible for DevOps book on LeanPub.

YAML, a simple configuration language

YAML's usage for describing configuration has been increasing rapidly in the past few years, and with the introduction of SaltStack and Ansible, YAML finally made its way into the server configuration management realm as a first class citizen.

YAML is a pretty simple language; it is a human-readable, machine-parsable syntax that allows for complex nested object, list, and array structures, so it is a great fit for a configuration management tool. Consider the following method of defining a list (or 'collection') of widgets:

widget:
  - foo
  - bar
  - fizz

This would translate into Python (using the PyYAML library employed by Ansible) as the following:

translated_yaml = {'widget': ['foo', 'bar', 'fizz']}

And what about a structured list/map in YAML?

widget:
  foo: 12
  bar: 13

The Python that would result:

translated_yaml = {'widget': {'foo': 12, 'bar': 13}}

A few things to note with both of the above examples:

• YAML will try to determine the type of an item automatically. So foo in the first example would be translated as a string, true or false would be a boolean, and 123 would be an integer. This post doesn't attempt to go further with this exploration, but realize that you might want to explicitly declare strings with quotes ('' or "") to minimize surprises.
• Whitespace matters! YAML uses spaces (literal space characters—not tabs) to define structure (mappings, array lists, etc.), so set your editor to use spaces for tabs. You can technically use either a tab or a space to delimit parameters (like apt: name=foo state=installed—you can use either a tab or a space between parameters), but it's generally preferred to use spaces everywhere, to minimize errors and display irregularities across editors and platforms.
• YAML syntax is robust and well-documented. Read through the official YAML Specification and/or the PyYAMLDocumentation to dig deeper.

A basic Ansible playbook

To use Ansible, you only need to know minimal YAML structure. Consider the following simple playbook:

---
# My Ansible playbook.
- hosts: all

  tasks:
    - name: Install foo.
      apt: pkg=foo state=installed

• The first line above denotes the beginning of some YAML—anything above that line shouldn't be parsed as YAML (but I wouldn't rely on all YAML parsers being so smart... so I generally leave YAML in .yml and add documentation as comments inline with the YAML).
• The second line is a comment. Comments start with # and can use multiple lines (as long as each line starts with #).
• The third line begins a list; in this case, a list of plays Ansible should run. Generally, playbooks only affect one set of hosts (in this case, all hosts defined in available/given inventories), but you can add additional plays by starting another new - hosts: [group] section or including another playbook with another play.
• For the first (and in this playbook, only) grouping of hosts, we define a list of tasks. The first task uses the apt module to install the foo package on a Debian-based system.

All well and good, right? Well, as you get deeper into Ansible and start defining more complex configuration, you might start seeing tasks like the following:

- name: Copy Phergie shell script into place.
  template: src=templates/phergie.sh.j2 dest=/home/{{ phergie_user }}/phergie.sh owner={{ phergie_user }} group={{ phergie_user }} mode=755

The one-line syntax (which uses Ansible-specific key=value shorthand for defining parameters) has some very positive attributes:

• Typical tasks (like installations and copies) are compact and readable (apt: pkg=apache2 state=installed is just about as simple as apt-get install -y apache2; in this way, an Ansible playbook feels very much like a shell script).
• Playbooks can be more compact, and more configuration can be displayed on one screen.
• Ansible's official documentation follows this format, and many existing roles and playbooks use one line for all parameters.

However, as highlighted in the above example, there are a few issues with this key=value syntax, namely you have to:

• Have a pretty large/widescreen monitor (able to display at least 120 characters comfortably)
• Use a source control UI that displays output in a very wide display (e.g. not GitHub, GitLab, Gogs, etc.)
• Read left-to-right
• Have a diff viewer that easily highlights inter-line differences
• Not worry about variable types being converted to strings in some situations

I argue that the shorthand syntax falls apart for more complicated, shared playbooks (especially roles), and I have a few ideas to help you make tasks more readable, better for version control software and diffing.

Methods for formatting Ansible tasks in YAML

Following a discussion over on the Ansible Project Google Group on YAML formatting best practices, and also the maintenance of dozens of roles and playbooks, I've finally settled on a few basic guidelines for my playbook tasks, and generally prefer using a multiline syntax rather than shorthand for more complex tasks.

Simple, straightforward tasks - shorthand/one-line (=)

For simpler tasks, I usually stick to the shorthand syntax, using key=value parameters.

- name: Install Nginx.
  yum: pkg=nginx state=installed

For any situation where an equivalent shell command would roughtly match what I'm writing in the YAML, I prefer this method, since it's immediately obvious what's happening, and it's highly unlikely any of the parameters (like state=installed) will change frequently during development.

Complex or 3+ parameter tasks - structured map (:)

For more complex tasks, like the longer template example above, I prefer the following format:

- name: Copy Phergie shell script into place.
  template:
    src: "templates/phergie.sh.j2"
    dest: "/home/{{ phergie_user }}/phergie.sh"
    owner: "{{ phergie_user }}"
    group: "{{ phergie_user }}"
    mode: 0755

A few notes on this syntax:

• The structure is all valid YAML, using the structured list/map syntax mentioned in the beginning of this post.
• Strings, booleans, integers, octals, etc. are all preserved (instead of being converted to strings).
• Each parameter must be on its own line, so you can't chain together mode: 0755, owner: root, user: root to save space.
• YAML syntax highlighting works slightly better for this format than key=value, since each key will be highlighted, and values will be displayed as constants, strings, etc.

A passable hybrid approach - folded scalars (>)

Another approach that's often used in the wild (I use it in many of my own work) is using the terse key=value parameter syntax as in Ansible's documentation, but splitting values over multiple lines using YAML's folded scalar syntax:

- name: Copy Phergie shell script into place.
  template: >
    src=templates/phergie.sh.j2
    dest=/home/{{ phergie_user }}/phergie.sh
    owner={{ phergie_user }} group={{ phergie_user }} mode=755

In YAML, the > character denotes a folded scalar, where every line that follows (as long as it's indented further than the first line) will be joined with the line above by a space. So the above YAML and the original template example will function exactly the same.

This syntax allows arbitrary splitting of lines on parameters, but it also doesn't preserve numeric, boolean, and other non-string types for values.

I have started to phase out this approach in my own work (and will be changing older examples in my book, Ansible for DevOps) in favor of the structure map style above. The only place where I can see the folded scalar approach being more helpful is for certain uses of the command and shell modules, where you need to pass in extra options:

- name: Install Drupal.
  command: >
    drush si -y
    --site-name="{{ drupal_site_name }}"
    --account-name=admin
    --account-pass={{ drupal_admin_pass }}
    --db-url=mysql://root@localhost/{{ domain }}
    chdir={{ drupal_core_path }}
    creates={{ drupal_core_path }}/sites/default/settings.php

Typically, if you can find a way to run a command without having to use creates and chdir, or very long commands (which are arguably unreadable either in single or multiline format!), it's better to do that instead of this monstrosity.

But sometimes the above is as good as you can do to keep unweildy tasks sane.

Summary

As I mentioned in the mailing list, one of Ansible's strengths is its flexibility; any one of the above methods of task definition is equally valid and functional. I have chosen to use the shorthand syntax for simpler tasks, and structured maps for more complex tasks, since they feel more maintainable and readable to my eye.

If you prefer to use a different syntax or conventions, that's not wrong. As with most programming and technical things, being consistent is more important than following a particular set of rules, especially if that set of rules isn't universally agreed upon.

I would encourage the use of one of these styles as a general rule, though, and also communicate as much to the people who will be working with you on your playbooks. Nothing's worse than debugging a complicated role and having to visually parse through three different YAML styles!