Deconstructing an Ansible playbook

This article describes the different parts of an Ansible playbook starting with a very broad overview of what Ansible is and how you can use it. Ansible is a way to use easy-to-read YAML syntax to write playbooks that can automate tasks for you. These playbooks can range from very simple to very complex and one playbook can even be embedded in another.

Installing httpd with a playbook

Now that you have that base knowledge let's look at a basic playbook that will install the httpd package. I have an inventory file with two hosts specified, and I placed them in the web group:

[root@ansible test]# cat inventory
[web]
ansibleclient.usersys.redhat.com
ansibleclient2.usersys.redhat.com

Let's look at the actual playbook to see what it contains:

[root@ansible test]# cat httpd.yml
---
- name: this playbook will install httpd
  hosts: web
  tasks:
    - name: this is the task to install httpd
      yum:
        name: httpd
        state: latest

Breaking this down, you see that the first line in the playbook is ---. This lets you know that it is the beginning of the playbook. Next, I gave a name for the play. This is just a simple playbook with only one play, but a more complex playbook can contain multiple plays. Next, I specify the hosts that I want to target. In this case, I am selecting the web group, but I could have specified either ansibleclient.usersys.redhat.com or ansibleclient2.usersys.redhat.com instead if I didn't want to target both systems. The next line tells Ansible that you're going to get into the tasks that do the actual work. In this case, my playbook has only one task, but you can have multiple tasks if you want. Here I specify that I'm going to install the httpd package. The next line says that I'm going to use the yum module. I then tell it the name of the package, httpd, and that I want the latest version to be installed.

[ Readers also liked: Getting started with Ansible ]

When I run the httpd.yml playbook twice, I get this on the terminal:

[root@ansible test]# ansible-playbook httpd.yml

PLAY [this playbook will install httpd] ************************************************************************************************************

TASK [Gathering Facts] *****************************************************************************************************************************
ok: [ansibleclient.usersys.redhat.com]
ok: [ansibleclient2.usersys.redhat.com]

TASK [this is the task to install httpd] ***********************************************************************************************************
changed: [ansibleclient2.usersys.redhat.com]
changed: [ansibleclient.usersys.redhat.com]

PLAY RECAP *****************************************************************************************************************************************
ansibleclient.usersys.redhat.com : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
ansibleclient2.usersys.redhat.com : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

[root@ansible test]# ansible-playbook httpd.yml

PLAY [this playbook will install httpd] ************************************************************************************************************

TASK [Gathering Facts] *****************************************************************************************************************************
ok: [ansibleclient.usersys.redhat.com]
ok: [ansibleclient2.usersys.redhat.com]

TASK [this is the task to install httpd] ***********************************************************************************************************
ok: [ansibleclient.usersys.redhat.com]
ok: [ansibleclient2.usersys.redhat.com]

PLAY RECAP *****************************************************************************************************************************************
ansibleclient.usersys.redhat.com : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
ansibleclient2.usersys.redhat.com : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

[root@ansible test]#

Note that in both cases, I received an ok=2, but in the second run of the playbook, nothing was changed. The latest version of httpd was already installed at that point.

To get information about the various modules you can use in a playbook, you can use the ansible-doc command. For example:

[root@ansible test]# ansible-doc yum
> YUM    (/usr/lib/python3.6/site-packages/ansible/modules/packaging/os/yum.py)
Installs, upgrade, downgrades, removes, and lists packages and groups with the `yum' package manager. This module only works on Python 2. If you require Python 3 support, see the [dnf] module.

  * This module is maintained by The Ansible Core Team
  * note: This module has a corresponding action plugin.
< output truncated >

It's nice to have a playbook that installs httpd, but to make it more flexible, you can use variables instead of hardcoding the package as httpd. To do that, you could use a playbook like this one:

[root@ansible test]# cat httpd.yml
---
- name: this playbook will install {{ myrpm }}
  hosts: web
  vars:
    myrpm: httpd
  tasks:
    - name: this is the task to install {{ myrpm }}
      yum:
        name: "{{ myrpm }}"
        state: latest

Here you can see that I've added a section called "vars" and I declared a variable myrpm with the value of httpd. I then can use that myrpm variable in the playbook and adjust it to whatever I want to install. Also, because I've specified the RPM to install by using a variable, I can override what I have written in the playbook by specifying the variable on the command line by using -e:

[root@ansible test]# cat httpd.yml
---
- name: this playbook will install {{ myrpm }}
  hosts: web
  vars:
    myrpm: httpd
  tasks:
    - name: this is the task to install {{ myrpm }}
      yum:
        name: "{{ myrpm }}"
        state: latest
[root@ansible test]# ansible-playbook httpd.yml -e "myrpm=at"

PLAY [this playbook will install at] ***************************************************************************************************************

TASK [Gathering Facts] *****************************************************************************************************************************
ok: [ansibleclient.usersys.redhat.com]
ok: [ansibleclient2.usersys.redhat.com]

TASK [this is the task to install at] **************************************************************************************************************
changed: [ansibleclient2.usersys.redhat.com]
changed: [ansibleclient.usersys.redhat.com]

PLAY RECAP *****************************************************************************************************************************************
ansibleclient.usersys.redhat.com : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
ansibleclient2.usersys.redhat.com : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

[root@ansible test]#

Another way to make the tasks more dynamic is to use loops. In this snippet, you can see that I have declared rpms as a list to have mailx and postfix. To use them, I use loop in my task:

 vars:
    rpms:
      - mailx
      - postfix

  tasks:
    - name: this will install the rpms
      yum:
        name: "{{ item }}"
        state: installed
      loop: "{{ rpms }}"

You might have noticed that when these plays run, facts about the hosts are gathered:

TASK [Gathering Facts] *****************************************************************************************************************************
ok: [ansibleclient.usersys.redhat.com]
ok: [ansibleclient2.usersys.redhat.com]

These facts can be used as variables when you run the play. For example, you could have a motd.yml file that sets content like:

“This is the system {{ ansible_facts['fqdn'] }}.
This is a {{ ansible_facts['distribution'] }} version {{ ansible_facts['distribution_version'] }} system.”

For any system where you run that playbook, the correct fully-qualified domain name (FQDN), operating system distribution, and distribution version would get set, even without you manually defining those variables.

[ Need more on Ansible? Take a free technical overview course from Red Hat. Ansible Essentials: Simplicity in Automation Technical Overview. ] 

Wrap up

This was a quick introduction to how Ansible playbooks look, what the different parts do, and how you can get more information about the modules. Further information is available from Ansible documentation.