Basic Ansible YAML syntax and structure

Now that we’ve learned how to create and structure Ansible YAML files, we’ll explore fundamental YAML components, such as dictionaries, lists, and scalars (strings, integers, and floats). We’ll also cover adding comments to your YAML files.

In this lesson, you will:

• Learn more about YAML dictionaries, lists, and scalars.

• Learn how to keep your Ansible code readable with YAML comments.

Dictionaries (key-value pairs)

YAML dictionaries associate keys with values and are often used in Ansible configurations. These configurations include defining variables, Ansible module parameters, and playbook settings. Let’s use a dictionary to set variables in our site.yml playbook file.

# site.yml
---
- name: Configure web server
  hosts: all
  become: true

  vars:
    http_port: 80
    max_clients: 200

In this example, vars is a dictionary that sets the values for http_port and max_clients variables. These variables can be used throughout the playbook.

Lists (Sequences)

Lists define a collection of items identified by leading hyphens (-). Ansible uses lists to specify multiple items under a key, such as tasks, hosts, or values for Ansible modules.

…Output omitted…  
  tasks:
    - name: Install apache
      ansible.builtin.package:
        name: httpd
        state: present
    - name: Write the apache config template file
      ansible.builtin.template:
        src: httpd.conf.j2
        dest: /etc/httpd.conf
       mode: 0644

Each task is an item under the tasks section. Note that each task starts with a hyphen (-) to indicate an item in the list. For example, - name: Install apache.

Scalars

Scalars are basic, single-value data types. In Ansible, scalars are primarily used to specify variable values, module parameters, and more. In this learning path, we will cover two fundamental YAML scalars, strings and integers, and how these are used in Ansible: 

• Strings: Strings are a sequence of characters. In Ansible, strings specify text values such as playbook and task names and Ansible module values.

• Integers: Integers are used in Ansible to specify numbers without a decimal point. Examples of integers used in values are port numbers, counts, sizes, and more.

Let’s look at our site.yml playbook for examples of strings and integers:

# site.yml
---
- name: Configure web server
  hosts: all
  become: true

  vars:
    http_port: 80
    max_clients: 200

In our site.yml example, the playbook name, Configure web server, is an example of a string. The http_port and max_clients variable values, 80 and 200, respectively, are integers. 

Special considerations for Ansible

Here are some things to consider:

• Quotation marks: Using quotation marks for strings YAML is optional. As a best practice for Ansible, avoid using quotation marks for strings.
• Boolean values (true/false): Use true and false for Ansible boolean values. For example, the become: true directive in the site.yml playbook above is an example of using it correctly.

Using YAML comments in Ansible

YAML comments begin with a # character. Everything following this character on the same line is not considered part of the YAML code. Adding comments to annotate your Ansible YAML files makes them more readable and easier to maintain. 

You can use YAML comments to:

• Document the purpose of a playbook.
• Explain why configuration choices were made.
• Explain complex Ansible tasks.
• Marking sections as To-dos.

Let’s follow Ansible best practices and add comments to the site.yml playbook:

---
# site.yml
# This Playbook installs the Apache web server and copies over the httpd.conf.j2 configuration file to the target host.
#
# TODO: restart the web service once the configuration is applied

- name: Configure web server
  hosts: all
  become: true

  vars:
    http_port: 80
    max_clients: 200 # Set 200 simultaneous web requests

  tasks:
    # Ensure httpd package is installed
    - name: Install apache
      ansible.builtin.package:
        name: httpd
        state: present

    - name: Write the apache config template file
      ansible.builtin.template:
        src: httpd.conf.j2
        dest: /etc/httpd.conf
        mode: 0644

Congratulations. You now know more about YAML dictionaries, lists, and scalars, as well as how to keep your code readable with YAML comments. Now it's time to apply what you've learned in the next lesson with a hands-on interactive exercise.