An Ansible Tutorial

In this tutorial, you’ll use Vagrant to create a virtual machine that will host a server, and you’ll use Ansible to modify the server in increasingly complex ways. To follow along, get the tutorial repo and cd to it, and start the Vagrant server:

(If you haven’t installed Vagrant, see Chapter 1 for instructions.)

Ansible reads declarative configuration files called playbooks and applies them to inventories. (I’ll explain what I mean by declarative soon.) Let’s apply our first playbook to an invetory. To apply a playbook, you use the ansible-playbook command, and you specify an inventory with the -i flag. Try this:

This means apply the playbook specified by the file playbooks/01.yml to the inventory specified by the file inventory-vagrant-server. Let’s unpack what Ansible’s doing by looking first at inventory-vagrant-server, then playbooks/01.yml.

The purpose of an inventory file is to tell Ansible which servers to run which commands on. The inventory file lets you specify how to connect to servers, and it lets you organize servers into groups. Here’s inventory-vagrant-server:

The first line, which starts with default, defines a server alias. The alias’s name is default, and it refers to a collection of variables that specify how to connect to a server. In this case, it’s saying connect to the IP address 127.0.0.1 using port 2222 for SSH, and connect as the user "vagrant" with the private key file at .vagrant/machines/default/virtualbox/private_key. (If you’re not familiar with SSH keys, Digital Ocean has a good tutorial.

The next bit of text, [webservers], defines a group. Groups allow you to organize servers by their function or role so that you can easily apply different playbooks to them. For example, you may be running a server cluster with ten application servers and two database servers. You’ll want to set up the application servers differently from the database servers; for example, you’d install nginx on the app servers, and postgres on the db servers. In just a minute you’ll see how playbooks can target groups.

The next line under [webservers] is default. That tells Ansible that the server default belongs to the webservers group. Similarly, the next couple lines define a database group and specify that the server default belongs to it.

So, this inventory file defines one server, the Vagrant virtual machine. It specifies how to connect to it, and it defines two groups: webservers and database. It specifies that the server belongs to both groups.

Now let’s look at the playbook file, playbooks/01.yml:

The file uses the YAML file format. If you’re not familiar with YAML, it basically lets you compactly define mappings (also known as key/value pairs or dictionaries) and sequences (arrays or lists).

The first line, hosts: webservers, is a key/value pair that specifies which server groups to run commands on. It means, apply this playbook to the hosts in the webservers group. The next two lines, become: true and become_method: sudo, tell Ansible to execute commands as root.

The next bit specifies how the server should get modified. First, there’s the key tasks. Whereas the value of the previous keys were scalars (i.e. the value for the key hosts is webservers), the value for tasks is a sequence of mappings. Each mapping has a dash character preceding it, and each specifies a task that Ansible runs. The task specification gets translated into a command that’s run on all the servers specified by hosts.

The first mapping has the keys name and file. It’s good practice to give each task a name key, even though it’s not required. The task’s name does not affect the command that is run in any way; rather, it serves as documentation.

The line file: path=/etc/foo.conf state=touch mode=0644 needs more explaining. Every task must define one and only one module to use, and the module’s arguments. Modules are what get executed on servers, and it’s useful to think of them as just shell scripts. In this case, by including the file key, we’re telling Ansible to use the file module. We’re giving it the arguments path=/etc/foo.conf, state=touch, and mode=0644. When Ansible executes this task, it will use the file module to create a file at /etc/foo.conf and give it permissions 0644.

The next task ensures that nginx is installed. It uses the apt module (apt is Ubuntu’s package manager) with the argumengs pkg: nginx, state: installed, update-cache: yes. Notice that the arguments are written as a YAML mapping rather than a single line of foo=bar pairs. This is just two different way of encoding the same information. These arguments are telling the apt module make sure the nginx package is installed, and make sure the apt cache is up to date.

This readability is one of the reasons I like Ansible. It’s pretty easy to tell what’s going on. I do want to call attention to a couple things, though.

Earlier, I mentioned that Ansible reads declarative files. This means that you specify the end state of your server, not how to achieve that state. In this small example file we’ve told Ansible that we want an end state such that /etc/foo.conf file exists and nginx is installed, but we haven’t told Ansible exactly what steps it should take to reach that state. We didn’t tell Ansible run touch /etc/foo.conf and `sudo apt-get install nginx`.

You can check that Ansible did in fact create /etc/foo.conf by running vagrant ssh from the command line. This will log you in to the Vagrant server, where you can check the file’s existence with ls /etc/foo.conf. You can also check that nginx is installed by running nginx -v.

Ansible playbooks can be made more flexible and modular by using variables. Our next playbook, playbooks/02.yml, paramaterizes our two tasks with the file_path and package variables:

When you apply this playbook with ansible-playbook -i inventory-vagrant-server playbooks/02.yml, Ansible will create the file /etc/bar.conf and install the wget package. The double braces, as in {{ file_path }}, are how you interpolate variable values into your YAML files.

You can also specify variable values on the command line:

This will create the file /etc/baz.conf.

When we go through the Sweet Tooth Ansible tasks, you’ll find that nearly every task relies on variables. Variables make the code more flexible and reusable, just like in real programs.

Most applications' server configurations include at least a staging environment where you can do testing and sanity checking, and a production environment that real users use. You’ll likely want to set some of your playbooks' variables to different values for each environment.

For example, with Community Picks I have a staging environment and a production environment. The staging environment logs files to /var/log/staging-community-picks and the production environment logs files to /var/log/www-community-picks. The log file location is stored in an Ansible variable.

One way to set the different variable values for different environments is by both a) creating an inventory for each environment, and b) defining the inventory using a different structure than the one we covered.

In the Ansible Basics section you learned that you can define an inventory with a single file, like the file inventory-vagrant-server. You can also define an inventory using a set of files in a directory, and you can see this in the inventories directory, which contains two sub-directories, staging and prod. If you look in staging, you’ll see a file named hosts and a directory named group_vars. In the group_vars directory you’ll see a file named webservers. The prod directory has the exact same structure.

The files in the group_vars directory are what allow you to set Ansible variables. In the file inventories/staging/group_vars/webservers there’s a single line:

This means that when you apply a playbook to the inventory defined by inventories/staging, the variable file_path will be set to /var/log/staging for all the tasks that Ansible runs on the servers in the webservers group.

For example, if you run ansible-playbook -i inventories/staging playbooks/03.yml, you’re saying apply the playbook playbooks/03.yml to the inventory inventories/staging. In inventories/staging/host, you’ll see that the Vagrant server belongs to the webservers group. Therefore, when Ansible runs the tasks in playbooks/03.yml on that server, it will set the file_path variable to /var/log/staging, and the result will be that it will create the file /var/log/staging. The inventory inventories/prod is identical except that file_path gets set to /var/log/prod.

If you stopped reading the tutorial now and proceeded to develop your own playbooks using only tasks and variables, you could actually accomplish quite a bit. In fact, when I first started using Ansible, I would just copy a playbook from one project to another and make a bunch of tweaks. This process yielded some of the advantages of treating infrastructure as code — for example, I could easily test out a server configuration on a VM and have confidence that a remote host would get ste up in exactly the same way — but it was still too cumbersome and error-prone. It was like copying and pasting some functions from one project to another over and over and slightly modifying them, instead of taking the time to properly refactor them into a library.

Roles are like libraries. Just like clojure jars and ruby gems, they’re a way of organizing code and packaging it for reuse. They package together tasks and default values for variables, and they can also package files and templates. The Sweet Tooth roles, for example, include tasks for installing nginx along with an nginx config file template.

If you want to create an Ansible role, you have to organize your files using a predefined structure. By default, Ansible looks for role definitions in the ./roles directory relative to the playbook you’re applying. Our next tutorial playbook, 03.yml, includes two roles, create-file and install-package:

There’s a roles directory in the playbooks directory, and the roles directory contains a directory named create-file and a directory named install-package; defining a role starts with creating a directory bearing the role’s name within the roles directory.

The role’s directory can include the directories tasks, defaults, files templates and a few others that aren’t relevant for us. You define a role’s tasks in tasks/main.yml and the default values for a role in defaults/main.yml. (You’ll see examples files and templates getting used when we go through the Sweet Tooth code.) Our create-file role defines tasks under playbooks/roles/create-file/tasks/main.yml. Open it and you’ll see a familiar site:

This is the task from 02.yml, copied and pasted and unindented one level. It still contains the variable file_path, which we set in 03.yml.

The install-package role similarly lifts the task from 02.yml and places it in playbooks/roles/install-package/tasks/main.yml:

However, 03.yml does not define a value for the package variable. Instead, it’s defined in playbooks/roles/install-package/defaults/main.yml. You can override this default value in 03.yml.

When you list roles in a playbook, as we’ve done in 03.yml, the roles' tasks are executed in the order that the roles are included, so in this case if we apply the 03.yml playbook Ansible will create the file /etc/qux.conf, and after that it will install git.