Playbooks are written in YAML like the configuration files and are the basis for Ansible’s configuration management and en-masse multi-machine deployment.
These are very powerful not only for declaring server configurations but also to orchestrate steps of any manual ordered process, even when the different steps must bounce back and forth between sets of machines in any order, as playbooks can launch tasks synchronously or asynchronously as required.
While it’s suitable to use the /usr/bin/ansible program for ad-hoc commands and tasks. Playbooks are better kept in source control and used to push out larger configurations, or assure the configurations of your remote systems are still in check.
1 – Playbook Examples
Here are some initial examples of Ansible playbooks. A playbook by definition is composed of one or more plays in a list.
The goal of each play is to map a group of hosts to some well-defined role, through actions within the play Ansible calls tasks. Put simply though, a task is nothing more than a call to a preset Ansible module.
By composing a playbook of multiple ‘plays’, it is possible to orchestrate multi-machine deployments. Running certain steps on all machines in the “webservers” group, then certain steps on the “databases” server group, and then more commands back on the “webservers” group, etc.
The first snippet and playbook sets up Apache webserver on hosts in the webservers group. Notice the variables declared, remote user in use, and handlers towards the end.
[alert-announce]
- —
- – hosts: webservers
- vars:
- http_port: 80
- max_clients: 200
- remote_user: root
- tasks:
- – name: ensure apache is at the latest version
- yum: name=httpd state=latest
- – name: write the apache config file
- template: src=/srv/httpd.j2 dest=/etc/httpd.conf
- notify:
- – restart apache
- – name: ensure apache is running (and enable it at boot)
- service: name=httpd state=started enabled=yes
- handlers:
- – name: restart apache
- service: name=httpd state=restarted
[/alert-announce]
This second example uses tasks that have really long parameters, and modules that take many parameters. When this is the case you can break tasks items over multiple lines to improve the playbook readability and structure. Breaking up tasks is achieved by using YAML dictionaries to supply the modules with their key=value arguments.
[alert-announce]
- —
- – hosts: webservers
- vars:
- http_port: 80
- max_clients: 200
- remote_user: root
- tasks:
- – name: ensure apache is at the latest version
- yum:
- name: httpd
- state: latest
- – name: write the apache config file
- template:
- src: /srv/httpd.j2
- dest: /etc/httpd.conf
- notify:
- – restart apache
- – name: ensure apache is running
- service:
- name: httpd
- state: started
- handlers:
- – name: restart apache
- service:
- name: httpd
- state: restarted
[/alert-announce]
This final example contains not just one but two plays. The first targets the webservers host group and the second targets the databases host group.
[alert-announce]
- —
- – hosts: webservers
- remote_user: root
- tasks:
- – name: ensure apache is at the latest version
- yum: name=httpd state=latest
- – name: write the apache config file
- template: src=/srv/httpd.j2 dest=/etc/httpd.conf
- – hosts: databases
- remote_user: root
- tasks:
- – name: ensure postgresql is at the latest version
- yum: name=postgresql state=latest
- – name: ensure that postgresql is started
- service: name=postgresql state=started
[/alert-announce]
See the ansible/ansible-examples GitHub repository for some fully-fledged and properly structured Playbook configuration examples.
2 – Playbook Hosts and Users
For each “play” in a playbook, you get to choose the servers/hosts in your infrastructure you want to target, and which remote Linux user to complete the steps in the play as (remember the steps are called tasks).
The hosts line at the start of a play is a list of one or more groups, or if needed a host pattern. The remote_user holds the name of the target Linux/Unix user account.
For example:
[alert-announce]
- —
- – hosts: webservers
- remote_user: root
[/alert-announce]
Remote users can also be set per task instead of just for the entire play. Such as in this example where the task test connection uses a different user to the overall play.
[alert-announce]
- —
- – hosts: webservers
- remote_user: root
- tasks:
- – name: test connection
- ping:
- remote_user: scarlz
[/alert-announce]
The become and become_method items allow a change of privileges from within the SSH user’s session. This is useful for using shell programs like sudo for tasks that need higher privileges.
[alert-announce]
- —
- – hosts: webservers
- remote_user: scarlz
- tasks:
- – service: name=nginx state=started
- become: yes
- become_method: sudo
[/alert-announce]
In these cases you must provide the necessary password using --ask-become-pass when running the playbook itself with ansible-playbook from the command line – covered later on.
Using become_user similarly allows a change of user from within the play’s SSH user shell session.
[alert-announce]
- —
- – hosts: webservers
- remote_user: scarlz
- become: yes
- become_user: postgres
[/alert-announce]
Let’s look more at the tasks themselves and what they can do.
3 – Playbook Tasks
As seen each play contains its own list of tasks. Tasks are executed in order, one at a time, against all machines matched by the host group or pattern. So keep in mind that all hosts are going to receive and process the same task directives issued.
Also when running a playbook, any hosts that end up with failed tasks are taken out of the rotation for the entire playbook run. If things fail, simply correct the playbook file (or host connectivity issue) and rerun it.
As seen in the first section of this post, the goal of each task is to execute a module, with set variables passed to that module if needed.
Here is an omitted example:
[alert-announce]
- – hosts: webservers
- vars:
- http_port: 80
- max_clients: 200
- remote_user: root
- tasks:
- – name: make sure apache is running
- service: name=httpd state=started
[/alert-announce]
Importantly though module use should also be “idempotent”. That is to say, when running a module multiple times in a sequence, it should have the same end result as if you had run it only once. One way to achieve this state of idem-potency in playbooks is to have a module check whether its desired final state has already been achieved, and if that state has been achieved, to instead exit without performing any actions.
So if all the modules a playbook uses are idempotent, then the playbook itself is likely to be idempotent too (overall), so re-running the playbook multiple times should be safe and not create any issues.
Note: The command and shell modules will typically rerun the same command issued again, which is fine if the command is something that does not change the outcome of its initial execution when run multiple times. There is also a “creates” flag available here which can be used to make these two modules idempotent.
Furthermore, every task should have a name, which is included in the output from running the playbook, and serves as more of a description than a moniker. Due to this, It is useful to provide good descriptions for each task step.
Note: If a
nameis not provided, the string fed to ‘action’ will be used for output.
As with most modules, the service the module takes arguments in the key=value format.
[alert-announce]
- tasks:
- – name: make sure apache is running
- service: name=httpd state=started
[/alert-announce]
The command and shell modules are the only modules that take a list of arguments and don’t use the key=value form as normal.
This makes them work in the same way as you would expect them to on the command line e.g.
[alert-announce]
- tasks:
- – name: disable selinux
- command: /sbin/setenforce 0
[/alert-announce]
The command and shell module care about return codes, so if you have a command where the successful exit code is not zero, you can alter it to this:
[alert-announce]
- tasks:
- – name: run this command and ignore the result
- shell: /usr/bin/somecommand || /bin/true
[/alert-announce]
If the action line of the module is getting too long, you can break it on a space character and indent any continued lines to improve readability.
[alert-announce]
- tasks:
- – name: Copy ansible inventory file to client
- copy: src=/etc/ansible/hosts dest=/etc/ansible/hosts
- owner=root group=root mode=0644
[/alert-announce]
Variables declared can be explicitly used in task action lines, not just in templates (templates not covered yet).
The variable is called using the word vhost inside of the curly braces, in the example below:
[alert-announce]
- – hosts: webservers
- vars:
- vhost: blog-site.conf
- remote_user: root
- tasks:
- – name: create a virtual host file for {{ vhost }}
- template: src=somefile.j2 dest=/etc/httpd/conf.d/{{ vhost }}
[/alert-announce]
To carry on the concept and practice introduced here of idem-potency in Ansible. The next section talks about handlers.
4 – Playbook Handlers
Modules should be idempotent as described in the last section, so they can relay back whether they have made a change on the remote system or not. Playbooks have the ability to recognize these changes and also have a basic event system that can be used to respond to change.
notify actions are triggered at the end of each block of tasks in a play, and will only be triggered once. Even if notified and triggered by multiple different tasks. For instance, multiple resources may indicate that Apache needs to be restarted because they have changed a config file, but Apache will only be restarted once to avoid multiple unnecessary restarts.
Here’s an example of restarting two services in a task when the contents of a file change, but only if the file changes. The items listed in the notify section of the task are called handlers.
[alert-announce]
- – name: template configuration file
- template: src=template.j2 dest=/etc/foo.conf
- notify:
- – restart memcached
- – restart apache
[/alert-announce]
Handlers are lists of tasks (not really any different from regular tasks) that are referenced by a globally unique name, and are notified by notifiers. If a handler is never referenced/notified it will not run. As inferred earlier, regardless of how many tasks notify a handler, it will run only once, and after all of the tasks complete in a particular play.
Here’s an example of a handlers section with some defined tasks:
[alert-announce]
- handlers:
- – name: restart memcached
- service: name=memcached state=restarted
- – name: restart apache
- service: name=apache state=restarted
[/alert-announce]
5 – Running Playbooks
Now that you’ve learned much of the groundwork for playbook syntax, we should look at how to run a completed playbook.
To run a playbook use the anisble-playbook command followed by the path to the playbook file. In this scenario it’s in the current working directory and named playbook.yml.
[alert-announce]
- $ ansible-playbook playbook.yml -f 10
[/alert-announce]
The -f 10 specifies the usage of 10 simultaneous Ansible processes at once.
When executing a playbook there will always be a summary of the nodes/hosts that were targeted and how they fared with the instructions. General failures and fatal unreachable attempts by the playbook execution are kept separate in the “counts”.
The --verbose flag tagged onto the ansible-playbook command results in a more detailed account of the results of a playbook run. Furthermore the --list-hosts flag shows which hosts are to be affected by a playbook before you run it.
It’s possible to invert the architecture of Ansible, forcing nodes/hosts check in to a central location instead of pushing configuration out externally, by using the ansible-pull script.
Run the help option to see details on this if interested.
[alert-announce]
- $ ansible-pull –help
[/alert-announce]
As an aside, some say that Ansible playbook output is vastly upgraded if the cowsay package is installed on your system.
[alert-announce]
- # Debian / Ubuntu
- $ sudo apt-get install cowsay
- # Arch Linux
- $ sudo pacman -S cowsay
[/alert-announce]
7 – Ansible Templating
Templates in Ansible are constructed using the Jinja2 Python templating language and reside in their own files. They are capable of referencing variables from outside sources, such as from within the playbook using the template and the outer Ansible file inventory e.g. a main.yml file within an upper /vars directory.
Templates are typically useful for setting up configuration files, to make them and other files more versatile or reusable among playbooks. They can have any file name but the .tpl or .j2 extensions are common.
Below is a template example for setting up an Apache virtual host. It uses a variable for setting up the document root on each Ansible host:
[alert-announce]
- <VirtualHost *:80>
- ServerAdmin webmaster@localhost
- DocumentRoot {{ doc_root }}
- <Directory {{ doc_root }}>
- AllowOverride All
- Require all granted
- </Directory>
- </VirtualHost>
[/alert-announce]
The inbuilt module template: is used to apply a template file in a task. For example, if you named a template file vhost.tpl and you placed it inside the same directory as your playbook, this is how you would make use of the template to replace the default Apache virtual host, on your Ansible hosts:
[alert-announce]
- – name: Alter the default Apache virtual host
- template: src=vhost.tpl dest=/etc/apache2/sites-available/000-default.conf
[/alert-announce]
8 – Roles in Playbooks
Roles work best for more complex playbooks that have many multiple but related tasks. Each role contains only the relevant data and information needed to carry out said tasks. As there are usually multiple stages to a task or set of tasks, playbooks can get very lengthy and congested with all their operations. So confining tasks to roles helps alleviate this problem.
As an example, a playbook that installs Nginx, likely involves adding the stable package repository, then installing the package itself, as well as setting up all the configuration for the webserver. The final configuration step no doubt requires extra data such as variables, files, dynamic templates, and more. These are bet kept in their own role’s area.
The file-system for a role looks like the below, where rolename is the root directory, and the options are the subsequent directory areas for each piece of information.
[alert-announce]
- rolename
- – files
- – handlers
- – meta
- – templates
- – tasks
- – vars
[/alert-announce]
Within each of the individual directory areas above, Ansible will search for a main.yml file automatically. Any every piece of configuration for the role in question is contained within these locations.
After understanding how each of these different concepts work together to create a playbook. You can go on to make your own from scratch, from other examples, or by converting your older setup scripts.
