10. Playbook Structure and Syntax in Ansible

In the previous section, we covered foundational Ansible concepts—particularly variables and facts. This section delves into the structure and syntax of Ansible Playbooks, laying the groundwork for defining and managing tasks in subsequent lessons.

What Is a Playbook?

An Ansible Playbook is a set of instructions describing how to configure and manage remote hosts. Written in YAML format, Playbooks are highly readable and easy to maintain. They are organized into plays, each specifying which hosts to target and what tasks to execute on them.

Basic Structure of a Playbook

A minimal Playbook typically includes the following components:

---
- hosts: webservers
  remote_user: ansible
  tasks:
    - name: Install nginx
      yum:
        name: nginx
        state: present

Key Components

1. File header: Begins with ---, indicating a YAML document.
2. hosts: Specifies the host group (or individual host) to which the play applies—referencing groups defined in your inventory file.
3. remote_user: Defines the user account used to connect to target hosts.
4. tasks: Lists the operations to be performed; this is the core of any play.
5. name: A descriptive label for the task, improving readability and maintainability.
6. Modules: Reusable Ansible units of logic—for example, yum, apt, copy, template, etc.

Syntax Details

• Playbooks use YAML, where indentation is strictly enforced. Indentation must be done with spaces—not tabs.
• A single Playbook file may contain multiple plays, each independently defined as needed.

Example: Multiple Plays

---
- hosts: webservers
  tasks:
    - name: Install nginx
      yum:
        name: nginx
        state: present

- hosts: dbservers
  tasks:
    - name: Install MySQL
      yum:
        name: mysql
        state: present

Here, two distinct plays are defined: one targeting the webservers group and another targeting dbservers.

Variables in Playbooks

Variables enable dynamic, reusable task definitions. They can be declared at various scopes—including playbook-level, host-level, or task-level.

Variable Usage Example

---
- hosts: webservers
  vars:
    package_name: nginx
  tasks:
    - name: Install web server
      yum:
        name: "{{ package_name }}"
        state: present

In this example, the variable package_name is defined and then referenced within the task using Jinja2 templating syntax ({{ ... }}). This approach enhances flexibility and reusability.

Conditional Execution

Playbooks support conditional logic via the when clause, allowing tasks to run only when specific criteria are met.

Conditional Execution Example

---
- hosts: webservers
  tasks:
    - name: Install nginx
      yum:
        name: nginx
        state: present
      when: ansible_os_family == "RedHat"

Here, the Install nginx task executes only if the target host’s operating system belongs to the RedHat family (e.g., RHEL, CentOS, Fedora).

Loops

Ansible supports iterative execution using loops—commonly implemented with with_items.

Loop Execution Example

---
- hosts: webservers
  tasks:
    - name: Install multiple packages
      yum:
        name: "{{ item }}"
        state: present
      with_items:
        - nginx
        - git
        - vim

This task installs each listed package (nginx, git, vim) sequentially on the target hosts.

Summary

This section introduced the fundamental structure and syntax of Ansible Playbooks—including how to declare hosts, define tasks, and invoke modules. We also explored variable usage, conditional execution with when, and basic looping with with_items. These core concepts form the essential foundation for the next topic: Defining and Managing Tasks in Playbooks.

If you’ve mastered this material, feel free to proceed to the next lesson: Writing Playbooks — Defining and Managing Tasks.