Ansible YAML Fundamentals

YAML (YAML Ain't Markup Language) is the language of Ansible playbooks, inventory files, and variable definitions. It is designed to be human-readable — closer to plain English than to programming syntax. However, YAML has specific rules about whitespace and structure that catch beginners off guard. This lesson teaches you YAML from the perspective of what Ansible actually uses, avoiding the full YAML specification in favour of the 20 percent of features that cover 80 percent of Ansible use cases.

The Golden Rule of YAML: Indentation with Spaces

YAML uses indentation to represent structure. The rules are absolute: use spaces, never tabs, and be consistent about how many spaces you use per level. Two spaces per indent level is the standard in Ansible.

YAML Data Types

Scalars (single values)

name: web-server-01        # String (quotes optional unless it contains special chars)
port: 80                   # Integer
enabled: true              # Boolean (true/false, yes/no, on/off all work)
ratio: 0.75                # Float
empty_value: ~             # Null (equivalent to null)

Lists

packages:
  - nginx
  - curl
  - vim

Or inline (flow style):

packages: [nginx, curl, vim]

Dictionaries (mappings)

server:
  name: web01
  ip: 192.168.1.10
  port: 80

Or inline: server: {name: web01, ip: 192.168.1.10, port: 80}

Nested structures

users:
  - name: alice
    groups:
      - sudo
      - developers
    shell: /bin/bash
  - name: bob
    groups:
      - developers
    shell: /bin/zsh

Strings and Quoting

Most strings do not need quotes. Use single quotes when the string contains a colon, hash, or leading/trailing spaces. Use double quotes when the string contains escape sequences like \n or variables to interpolate.

message: Hello World                    # No quotes needed
note: "Use this: with colons"           # Double quotes
path: '/etc/nginx/nginx.conf'           # Single quotes
multiline: |                            # Literal block scalar - preserves newlines
  Line one
  Line two
  Line three
folded: >                               # Folded block scalar - joins lines with spaces
  This is a very long line that
  is folded for readability.

Comments

YAML comments start with # and extend to the end of the line. Use comments liberally in playbooks to explain intent:

# Install required packages for the web tier
- name: Install Nginx
  apt:
    name: nginx
    state: present

Common YAML Mistakes in Ansible

Mistake 1: Tabs instead of spaces

YAML strictly forbids tabs. Configure your text editor to convert tabs to spaces automatically. Most editors support this.

Mistake 2: Inconsistent indentation

# Wrong - mixing 2 and 4 space indentation
- name: Example
  tasks:
      - name: bad indent  # 6 spaces instead of 4

Mistake 3: Missing space after colon

name:web01   # Wrong - no space after colon
name: web01  # Correct

Mistake 4: Unquoted strings with special characters

message: Hello: World   # Error - unquoted colon in value
message: "Hello: World" # Correct

Validating YAML

Use the ansible-playbook --syntax-check command to validate YAML syntax before running:

ansible-playbook --syntax-check my-playbook.yml

The yamllint tool provides more detailed YAML validation:

pip3 install yamllint
yamllint my-playbook.yml

Try This: Write and Validate a YAML Structure

Create a file called test.yml with this structure representing a web server configuration:

server:
  hostname: web01
  ip_address: 192.168.1.10
  services:
    - name: nginx
      port: 80
      enabled: true
    - name: php-fpm
      port: 9000
      enabled: true
  admins:
    - alice
    - bob

Validate it with yamllint test.yml. Intentionally introduce a tab character and re-validate to see what the error looks like. This teaches you to recognise YAML errors quickly.

Summary

YAML uses indentation to represent structure, with spaces only — never tabs. The three core data types are scalars, lists, and dictionaries, which can be nested arbitrarily. Special characters in strings require quoting. The | and > block scalars handle multi-line strings. Validate YAML syntax early and often with --syntax-check and yamllint. Clean YAML is the foundation of readable, maintainable Ansible playbooks.