Skip to main content

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

Although YAML is considered easy to understand, its syntax can be quite confusing. Use this guide to the basics.
YAML for beginners

Image by inspireus from Pixabay

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
   - 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.

  - 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
    - name: Example mail
        host: #Mention the SMTP hostname here
        port: 587 #Mention the SMTP port here
        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.

Topics:   Ansible   Programming  
Author’s photo

Pratheek Prabhakaran

Pratheek is a Sysadmin at a Fortune 500 company in India where he specializes in IT automation with Ansible. He has experience in SAP Basis, RHEL Satellite, AWS Cloud, and VMware Administration. An avid reader, cricketer, and artist. More about me

Try Red Hat Enterprise Linux

Download it at no charge from the Red Hat Developer program.