Ansible - 6. Playbook syntax

 An Ansible Playbook is essentially a configuration file, written in YAML, that defines a set of tasks to be executed on a specific group of remote hosts. Think of it as a detailed script or a "to-do list" for your infrastructure.

1. The Play (- name: and hosts:)

The Play is the top-level grouping that defines where and how the tasks will run.

Parameter	Example Value	Description
---	---	YAML Start Indicator. This marks the beginning of the YAML file.
- name:	Report Filesystem Usage	A descriptive title for this entire block of work.
hosts:	all or db_servers	Target Selection. Specifies which hosts from your inventory file (e.g., inventory/hosts) the tasks should run on.
gather_facts:	no	Whether Ansible should automatically collect system data (facts) like OS version, memory, etc., before running tasks. Setting it to no can speed up simple plays.
become:	yes	Privilege Escalation. A playbook-level setting that tells Ansible to use sudo or similar methods (like become in your guide) to run tasks with elevated permissions (often root).

 2. Variables (vars:)

This optional section is used to define reusable values specific to the playbook. This promotes consistency and makes the playbook easier to maintain.

Parameter	Example Use	Description
vars:	remote_user: oracle	Defines a variable. You can then use it in tasks like: user: "{{ remote_user }}".

3. Tasks (tasks:)

Tasks are the specific actions Ansible will execute, and they are always based on an Ansible Module. Each task runs sequentially on all targeted hosts.

Parameter	Example Value	Description
tasks:	(List of tasks)	The main list of steps to execute.
- name:	Execute 'df -h' command	A brief, informative description of the task's purpose.
ansible.builtin.command:	df -h	The Module. This specifies the Ansible module to use. command is used to run basic shell commands.
register:	disk_usage_output	Capturing Output. This saves the output or result of the task into a variable for use in subsequent tasks.
ansible.builtin.debug:	msg: "{{ var_name.stdout }}"	A module used purely to print messages or variable content to the terminal.

An Ansible Playbook provides the blueprint for automation: "Run this list of tasks (using these modules) on these specific servers." It’s idempotent, meaning you can run it repeatedly, and it will only make changes if the system is not already in the desired state.

In YAML (and therefore in Ansible playbooks), indentation means the number of spaces at the beginning of a line that show the structure and hierarchy of the data.

Unlike some programming languages, YAML does not use braces {} or keywords to mark blocks — it uses spaces.

For example ,

[oracle@oel01db ansible-project]$ cat playbooks/setup_list.yml

- name: Check the log file contents on /var/log   # <-- Play starts here

  hosts: db_servers                  # Hosts this play targets  (2 spaces)

  gather_facts: no # (any other vars -2 spaces)

  tasks:                             # All tasks in this play (2 spaces)

    - name: Show all .log files  # Individual task1 (4 spaces)

      ansible.builtin.shell: ls /var/log | grep .log # Module details (6 spaces)

      register: log_files  # also under the task (6 spaces)

    - name: Display log files  #Individual task2 (4 spaces)

      ansible.builtin.debug: #Module details (6 spaces)

        msg: "{{ log_files.stdout }}" # (Module parameter - 8 spaces)

[oracle@oel01db ansible-project]$

In this example:

- name: Display log files
  ansible.builtin.debug:
    msg: "{{ log_files.stdout }}"

• ansible.builtin.debug: → 6 spaces under the play (same level as the previous task module)

• msg: → 8 spaces → nested under ansible.builtin.debug

✅ This 8 space is because msg is a parameter of the debug module, so it must be nested under the module.

Visual hierarchy

play (0 spaces)
  tasks: (2 spaces)
    - task (4 spaces)
      module (6 spaces)
        module parameter (8 spaces)

So for every module parameter, add extra 2 spaces relative to the module line.

YAML start indicator --- is not mandatory, but it is recommended.

The  reason being:

• Clarity: Shows explicitly where the YAML file starts.

• Multiple documents: YAML supports multiple documents in one file, separated by ---

For example,

---
- name: DB play
  hosts: db_servers
  tasks:
    - command: uptime
---
- name: Web play
  hosts: web_servers
  tasks:
    - command: ls /var/www

Summary

Reason for multiple plays
Why everything can’t be in one play
Different host groups
One play can target only one set of hosts
Different privileges
become: yes may not apply to all hosts
Sequential execution
Some tasks must finish before moving to others
Logical separation
Easier to read, maintain, and reuse


✅ Rule of thumb:
If all tasks are for the same hosts, same variables, same privileges → bundle in a single play.
If you need different hosts, different variables, or sequential control → use multiple plays, optionally separated by --- for clarity.