How to use YAML nesting, lists, and comments in Ansible playbooks

To automate with Ansible, you must be familiar with YAML, the human-readable language used to define the logic in Ansible playbooks. YAML stands for "Yet Another Markup Language" or "YAML Ain't Markup Language" (a recursive acronym). YAML is often used for writing configuration files. Although YAML is considered simple and easy to understand, the YAML syntax can be quite confusing. This article digs a little deeper into some YAML basics.

Understand nesting

YAML was first introduced in the early 2000s. YAML files use a .yml or .yaml extension, and YAML files usually start with --- and end with ..., though this is optional. You can use any source code editor like Vim or Emacs, or any other integrated development environment (IDE) to write YAML files. A simple key-value pair is used in YAML to represent data.

YAML uses Python-style indentation to indicate nesting. There are no strict requirements on how many spaces to use for the indentation in YAML, but there are two basic rules:

• Data elements at the same level in the hierarchy must have the same indentation. In the example below, register, until, retries, and so forth must have the same indentation, as they are all part of the same task.
• Items that are children of another item must be indented more than their parents. In the example, url, method, and return_content are children of the uri parent item and hence are indented more.

---
- name: Check URL
  hosts: all
  gather_facts: True
  tasks:
   - uri:
        url: "{{ urlpath }}"
        method: GET
        return_content: yes
     register: result
     until: result.status == 200
     retries: 30
     delay: 20
     delegate_to: localhost
   - debug:
       msg: "{{ result.status }} - {{ result.msg }}"
...

Instead of representing key-value pairs as an indented block, you can also write them in an inline block format enclosed in curly braces.

name: newrole
service: httpd
state: started
port: 80

The above can also be written as:

{name: newrole, service: httpd, state: started, port: 80}

[ Get started with IT automation with the Ansible Automation Platform beginner's guide. ]

Use lists

Ansible playbooks use YAML lists to represent a list of items. You can express them in two ways, shown below.

Each element in the list is represented in YAML as a new line with the same indentation, starting with - followed by a space.

hosts:
  - servera
  - serverb
  - serverc

The above can also be written as comma-separated items:

hosts: [servera, serverb, serverc]

Use YAML strings

YAML comments improve the readability of Ansible playbooks. Identify comments by using the hash (#) symbol. YAML strings can be represented within single or double quotes. For multiline strings, you can use the vertical bar (|) pipe character or the greater-than (>) character. The difference between the two is that the vertical bar character preserves the new line while the greater-than character folds the new line and converts it into spaces.

For example:

---
- name: Send mail
  tasks:
    - name: Example mail
      community.general.mail:
        host: smtp.gmail.com #Mention the SMTP hostname here
        port: 587 #Mention the SMTP port here
        to: username@gmail.com
        subject: 'Ansible: System generated mail'
        body: |
           This is a system generated mail
           from the {{ ansible_facts['hostname'] }} server.
      delegate_to: localhost
...

Wrap up

This article gives a brief introduction and overview of YAML nesting, lists, and strings with a few examples. I hope this article reinforces YAML's reputation as a simple, easy-to-understand, human-readable language. For a technical overview of YAML's structure, read YAML for beginners.