Getting started writing your first playbook

What is a Playbook?

Playbooks are essentially sets of instructions (plays) that you send to run on a single target or groups of targets (hosts). Think about the instructions you get for assembling an appliance or furniture. The manufacturer includes instructions so you can put the parts together in the correct order. When followed in order, the furniture looks like what was purchased.

That's basically how a playbook works.

Modules

The Playbook we're building will install a web server on a target RHEL/CentOS 7 host, then write an index.html file based on a template file that will reside with the final Playbook. You'll be able to take the example Playbook and additional files from this blog and test it out for yourself. While going over the example Playbook, we'll explain the modules that are used.

Authors

The author adds instructions for the modules to run, often with additional values (arguments, locations, etc.). The target host has modules run against it in the order the Playbook lays out (with includes or other additional files). The host's state is changed (or not) based on the results of the module running, which Ansible and Tower displays in output.

Running Playbooks

Keeping that in mind, you're still going to need to understand a few things about running Playbooks. With the furniture analogy, a Playbook is shorthand to tell the modules to perform a task. You must understand the following to run your Playbook successfully:

1. The target

Because the Playbooks are providing direction and interactivity with the modules, Ansible assumes you know how to do what you're trying to do and automates it. That's why Playbooks are like instructions or directions - you're telling the automated parts how you want the task configured. You'll still need to understand the target you're running the Playbook against.

2. The tasks

If part of the Playbook needs to start the web server, you're going to need to know how that's done so you know to use the service module and start the web server by name. If the Playbook is installing software, then you have to know how installation is done on the target. You're also still going to need to understand the basics of the tasks being performed. Does the software you're installing have a configuration setup to it? Are there multiple steps that require conditions or argument values? If there are variables that are being passed, these will all need to be understood by those constructing a Playbook as well.

Example Playbook

We'll share an example Playbook with a simple play to demonstrate what I've explained. The target host will be a RHEL/CentOS 7 base install. There will be a web server installed (NGINX) and then an index.html file will be created in the default webroot. After the install and file tasks are completed the service will be started.
*Note to run this example Playbook with Ansible Tower your inventory and credentials must be configured. 

Playbooks start with the YAML three dashes (---) followed by:

Name: good for keeping the Playbooks readable

Hosts: identifies the target for Ansible to run against

Become statements: true statement is included here to ensure nginx installs without a problem (it's not always required)

---
- name: Install nginx
  hosts: host.name.ip
  become: true

On the same indent level as the three prior statements will go the tasks: statement, after which any plays are listed another indent deeper (per YAML nesting). There are two tasks listed but both are using the Yum module. The first Yum task is adding the epel-release repo so that nginx can be installed. Once epel is present Yum is used to install the nginx package.

The state: present statement lets Ansible check the state on the target first before performing any further action. In both cases if the repo or package is already present, Ansible knows it doesn't have to do any more for this task and continues.

tasks:
  - name: Add epel-release repo
    yum:
      name: epel-release
      state: present

  - name: Install nginx
    yum:
      name: nginx
      state: present

The default install page for nginx is fine if you want to test that nginx installed properly, but you might have a basic html file that you'd like to have as your confirmation. For simplicity, the template index file is in the same directory I'll run the Playbook from for the example. The destination is simply the default for nginix with no configured sites.

  - name: Insert Index Page
    template:
      src: index.html
      dest: /usr/share/nginx/html/index.html

The last thing the Playbook will do is make sure that the nginx service has been started (and if not, start it).

- name: Start NGiNX
    service:
      name: nginx
      state: started

The entire Playbook is about the same length as the introduction paragraph:

---
- name: Install nginx
  hosts: host.name.ip
  become: true

  tasks:
  - name: Add epel-release repo
    yum:
      name: epel-release
      state: present

  - name: Install nginx
    yum:
      name: nginx
      state: present

  - name: Insert Index Page
    template:
      src: index.html
      dest: /usr/share/nginx/html/index.html

  - name: Start NGiNX
    service:
      name: nginx
      state: started