Ansible Fundamentals · Module 06 of 12

YAML without fear

Learn only the YAML structures needed to read and write clear Ansible playbooks.

Learning objectives

By the end of this module, you should be able to:

Recognize mappings and lists.
Use consistent indentation and quoting.
Read a task without getting distracted by YAML syntax.

YAML represents structured data

You do not need to become a YAML expert before using Ansible. Most beginner playbooks use mappings (key-value pairs), lists and nested combinations of the two.

Indentation represents structure, so consistency matters. Use spaces rather than tabs and keep playbooks visually simple.

A playbook is a list of plays

The leading dash before a play means 'this is an item in a list'. Inside the play, keys such as name, hosts, become and tasks form a mapping. tasks itself contains another list, where each item is a task.

Quote when ambiguity is possible

Quote values containing special characters, template expressions or values that YAML might interpret unexpectedly. File modes are commonly quoted, for example '0644'. Clear quoting is preferable to relying on subtle parser behaviour.

Worked examples

See the idea in practice.

Mapping and list

web:
  hosts:
    web01:
      ansible_host: 192.0.2.21
    web02:
      ansible_host: 192.0.2.22

web and hosts are mapping keys.
web01 and web02 are nested host keys.
Indentation shows which values belong together.

Task list

tasks:
  - name: Install nginx
    ansible.builtin.package:
      name: nginx
      state: present

  - name: Start nginx
    ansible.builtin.service:
      name: nginx
      state: started

Each dash introduces one task.
Each task uses one action module.
Module arguments are nested under the module name.

Hands-on lab

Lab — Read YAML as structure

Goal: Practice identifying lists, mappings and nesting before running a playbook.

STEP 1

Create syntax.yml

- name: YAML practice
  hosts: web
  become: true
  tasks:
    - name: Ensure a directory exists
      ansible.builtin.file:
        path: /tmp/ansible-demo
        state: directory
        mode: '0755'

STEP 2

Run syntax validation

ansible-playbook -i inventory.ini syntax.yml --syntax-check

STEP 3

Intentionally break indentation, rerun, then repair it

Move one module argument to the wrong indentation level and observe the parser error. Restore the correct structure before continuing.

Verify

--syntax-check succeeds after the file is repaired.
You can point to the play, task list, module and module arguments.

Expected outcome

The learner understands the YAML shape instead of memorizing indentation blindly.

If it fails

Read YAML errors from the first indicated line upward; the actual structural mistake may be just before the reported location.
Avoid tabs and inconsistent indentation.

Real-world connection

Readable YAML is operational safety: reviewers should be able to understand a change before it reaches production.

Avoid these traps

Common mistakes

Using tabs for indentation.
Copying YAML without understanding which values are lists versus mappings.
Leaving file modes unquoted and relying on implicit numeric interpretation.

Knowledge check

Can you explain it without looking back?

Open each answer only after you have tried to answer the question yourself.

1What does a leading dash usually represent in YAML?

An item in a list.

2Why does indentation matter?

Indentation expresses parent-child structure in YAML.

3What command can validate playbook syntax without executing tasks?

ansible-playbook <playbook> --syntax-check.