Ansible

Ansible: What Is It Good For?

Ansible is often described as a configuration management tool, and is typically mentioned in the same breath as Chef, Puppet, and Salt. When we talk about configuration management, we are typically talking about writing some kind of state description for our servers, and then using a tool to enforce that the servers are, indeed, in that state: the right packages are installed, configuration files contain the expected values and have the expected permissions, the right services are running, and so on. Like other configuration management tools, Ansible exposes a domain-specific language (DSL) that you use to describe the state of your servers.

These tools also can be used for doing deployment as well. When people talk about deployment, they are usually referring to the process of taking software that was written in-house, generating binaries or static assets (if necessary), copying the required files to the server(s), and then starting up the services. Capistrano and Fabric are two examples of open-source deployment tools. Ansible is a great tool for doing deployment as well as configuration management. Using a single tool for both configuration management and deployment makes life simpler for the folks responsible for operations.

Some people talk about the need for orchestration of deployment. This is where multiple remote servers are involved, and things have to happen in a specific order. For example, you need to bring up the database before bringing up the web servers, or you need to take web servers out of the load balancer one at a time in order to upgrade them without downtime. Ansible’s good at this as well, and is designed from the ground up for performing actions on multiple servers. Ansible has a refreshingly simple model for controlling the order that actions happen in.

Finally, you’ll hear people talk about provisioning new servers. In the context of public clouds such as Amazon EC2, this refers to spinning up a new virtual machine instance. Ansible’s got you covered here, with a number of modules for talking to clouds, including EC2, Azure, Digital Ocean, Google Compute Engine, Linode, and Rackspace, as well as any clouds that support the OpenStack APIs.

Architecture

As with most configuration management software, Ansible has two types of servers: controlling machines and nodes. First, there is a single controlling machine which is where orchestration begins. Nodes are managed by a controlling machine over SSH. The controlling machine describes the location of nodes through its inventory.

Agentless

In contrast with popular configuration management software — such as Chef, Puppet, and CFEngine — Ansible uses an agentless architecture.[14] With an agent-based architecture, nodes must have a locally installed daemon that communicates with a controlling machine. With an agentless architecture, nodes are not required to install and run background daemons to connect with a controlling machine. This type of architecture reduces the overhead on the network by preventing the nodes from polling the controlling machine.

Playbook

Playbooks are Ansible’s configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process.

I like to think of Ansible playbooks as executable documentation. It’s like the README file that describes the commands you had to type out to deploy your software, except that the instructions will never go out-of-date because they are also the code that gets executed directly.

If Ansible modules are the tools in your workshop, playbooks are your instruction manuals, and your inventory of hosts are your raw material.

In Ansible, a script is called a playbook. A playbook describes which hosts (what Ansible calls remote servers) to configure, and an ordered list of tasks to perform on those hosts.

To execute the playbook using the ansible-playbook command. In the example, the playbook is named webservers.yml, and is executed by typing:

1
$ ansible-playbook webservers.yml

Ansible will make SSH connections in parallel to web1, web2, and web3. It will execute the first task on the list on all three hosts simultaneously. In this example, the first task is installing the nginx apt package (since Ubuntu uses the apt package manager), so the task in the playbook would look something like this:

1
2
- name: install nginx
apt: name=nginx

Ansible will:

  1. Generate a Python script that installs the nginx package.
  2. Copy the script to web1, web2, and web3.
  3. Execute the script on web1, web2, web3.
  4. Wait for the script to complete execution on all hosts.

Ansible will then move to the next task in the list, and go through these same four steps. It’s important to note that:

  • Ansible runs each task in parallel across all hosts.
  • Ansible waits until all hosts have completed a task before moving to the next task.
  • Ansible runs the tasks in the order that you specify them.

Variable

Variable names should be letters, numbers, and underscores. Variables should always start with a letter.

foo_port is a great variable. foo5 is fine too.
foo-port, foo port, foo.port and 12 are not valid variable names.

Defining Variables in Playbooks
The simplest way to define variables is to put a vars section in your playbook with the names and values of variables.

Ansible also allows you to put variables into one or more files, using a section called vars_files.

We would replace the vars section with a vars_files that looks like this:

1
2
3
4
5
6
7
8
9
vars_files:
- nginx.yml


## nginx.yml
key_file: /etc/nginx/ssl/nginx.key
cert_file: /etc/nginx/ssl/nginx.crt
conf_file: /etc/nginx/sites-available/default
server_name: localhost

To debug variable

1
- debug: var=myvarname

Registering Variables

Often, you’ll find that you need to set the value of a variable based on the result of a task. To do so, we create a registered variable using the register clause when invoking a module.

In order to use the login variable later, we need to know what type of value to expect. The value of a variable set using the register clause is always a dictionary, but the specific keys of the dictionary are different, depending on the module that was invoked.

ACCESSING DICTIONARY KEYS IN A VARIABLE
If a variable contains a dictionary, then you can access the keys of the dictionary using either a dot (.) or a subscript ([]).

facts

When Ansible gathers facts, it connects to the host and queries the host for all kinds of details about the host: CPU architecture, operating system, IP addresses, memory info, disk info, and more. This information is stored in variables that are called facts, and they behave just like any other variable does.

Here’s a simple playbook that will print out the operating system of each server:

1
2
3
4
5
- name: print out operating system
hosts: all
gather_facts: True
tasks:
- debug: var=ansible_distribution

Viewing All Facts Associated with a Server
Ansible implements fact collecting through the use of a special module called the setup module. You don’t need to call this module in your playbooks because Ansible does that automatically when it gathers facts. However, if you invoke it manually with the ansible command-line tool, like this:

$ ansible server1 -m setup

interactive mode

If Ansible did not succeed, add the -vvvv flag to see more details about the error:

$ ansible testserver -i hosts -m ping -vvvv

We can see that the module succeeded. The “changed”: false part of the output tells us that executing the module did not change the state of the server. The “ping”: “pong” text is output that is specific to the ping module.

Simplifying with the ansible.cfg File

We had to type a lot of text in the inventory file to tell Ansible about our test server. Fortunately, Ansible has a number of ways you can specify these sorts of variables so we don’t have to put them all in one place.

Right now, we’ll use one such mechanism, the ansible.cfg file, to set some defaults so we don’t need to type as much.

WHERE SHOULD I PUT MY ANSIBLE.CFG FILE?

Ansible looks for an ansible.cfg file in the following places, in this order:

File specified by the ANSIBLE_CONFIG environment variable

./ansible.cfg (ansible.cfg in the current directory)

~/.ansible.cfg (.ansible.cfg in your home directory)

/etc/ansible/ansible.cfg

I typically put an ansible.cfg in the current directory, alongside my playbooks. That way, I can check it into the same version control repository my playbooks are in.

Run command remotely

I like to use the ansible command-line tool to run arbitrary commands on remote machines, like parallel SSH. You can execute arbitrary commands with the command module. When invoking this module, you also need to pass an argument to the module with the -a flag, which is the command to run.

For example, to check the uptime of our server, we can use:

$ ansible testserver -m command -a uptime

The command module is so commonly used that it’s the default module, so we can omit it:

$ ansible testserver -a uptime
$ ansible testserver -a “tail /var/log/dmesg”

inventory

WARNING
Although Ansible adds the localhost to your inventory automatically, you have to have at least one other host in your inventory file; otherwise, ansible-playbook will terminate with the error:

ERROR: provided hosts list is empty

property “Changed”

The changed key is present in the return value of all Ansible modules, and Ansible uses it to determine whether a state change has occurred. For the command and shell module, this will always be set to true unless overridden with the changed_when clause

ignore error

Ignoring when a module returns an error

1
2
3
4
5
- name: Run myprog
command: /opt/myprog
register: result
ignore_errors: True
- debug: var=result

Data type

All members of a list are lines beginning at the same indentation level starting with a “- “ (a dash and a space):

1
2
3
4
5
6
7
8
---
# A list of tasty fruits
fruits:
- Apple
- Orange
- Strawberry
- Mango
...

A dictionary is represented in a simple key: value form (the colon must be followed by a space):

1
2
3
4
5
# An employee record
martin:
name: Martin D'vloper
job: Developer
skill: Elite

More complicated data structures are possible, such as lists of dictionaries, dictionaries whose values are lists or a mix of both:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang

Dictionaries and lists can also be represented in an abbreviated form if you really want to:

1
2
3
---
martin: {name: Martin D'vloper, job: Developer, skill: Elite}
fruits: ['Apple', 'Orange', 'Strawberry', 'Mango']

These are called “Flow collections”.

span multiple lines

Values can span multiple lines using | or >. Spanning multiple lines using a “Literal Block Scalar” | will include the newlines and any trailing spaces. Using a “Folded Block Scalar” > will fold newlines to spaces; it’s used to make what would otherwise be a very long line easier to read and edit. In either case the indentation will be ignored. Examples are:

1
2
3
4
5
6
7
8
9
include_newlines: |
exactly as you see
will appear these three
lines of poetry

fold_newlines: >
this is really a
single line of text
despite appearances

commands

file

file - Sets attributes of files

Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules support the same options as the file module - including copy, template, and assemble.

1
2
3
4
5
6
7
8
9
10
11
# change file ownership, group and mode. When specifying mode using octal numbers, first digit should always be 0.
- file:
path: /etc/foo.conf
owner: foo
group: foo
mode: 0644
- file:
path: /work
owner: root
group: root
mode: 01777

delegation

This isn’t actually rolling update specific but comes up frequently in those cases.

If you want to perform a task on one host with reference to other hosts, use the ‘delegate_to’ keyword on a task. This is ideal for placing nodes in a load balanced pool, or removing them. It is also very useful for controlling outage windows. Be aware that it does not make sense to delegate all tasks, debug, add_host, include, etc always get executed on the controller. Using this with the ‘serial’ keyword to control the number of hosts executing at one time is also a good idea:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
---

- hosts: webservers
serial: 5

tasks:

- name: take out of load balancer pool
command: /usr/bin/take_out_of_pool {{ inventory_hostname }}
delegate_to: 127.0.0.1

- name: actual steps would go here
yum:
name: acme-web-stack
state: latest

- name: add back to load balancer pool
command: /usr/bin/add_back_to_pool {{ inventory_hostname }}
delegate_to: 127.0.0.1

These commands will run on 127.0.0.1, which is the machine running Ansible. There is also a shorthand syntax that you can use on a per-task basis: ‘local_action’. Here is the same playbook as above, but using the shorthand syntax for delegating to 127.0.0.1:

1
2
3
4
5
6
7
8
9
10
11
12
13
---

# ...

tasks:

- name: take out of load balancer pool
local_action: command /usr/bin/take_out_of_pool {{ inventory_hostname }}

# ...

- name: add back to load balancer pool
local_action: command /usr/bin/add_back_to_pool {{ inventory_hostname }}

A common pattern is to use a local action to call ‘rsync’ to recursively copy files to the managed servers. Here is an example:

1
2
3
4
5
6
---
# ...
tasks:

- name: recursively copy files from management server to target
local_action: command rsync -a /path/to/files {{ inventory_hostname }}:/path/to/target/

Note that you must have passphrase-less SSH keys or an ssh-agent configured for this to work, otherwise rsync will need to ask for a passphrase.

dev experience
lead