Ansible

01

The problem

Four machines. Three of them should be serving nginx on port 8080, with a config you can read, a firewall rule, and the service enabled at boot. The fourth needs a database. You could open four terminals — and then do it again next month, from memory, hoping you remember which of the four you already did.

Ansible is that list written down, in a form a machine can carry out against all four — and safely carry out twice.

02

One host, one module

Start with no file at all. Ansible can run a single module against a single host from the command line, and everything else on this page is that, repeated and written down.

$ ansible -i inventory/hosts.ini web1 -m ansible.builtin.ping
  does SSH work, and is there a Python at the other end
web1 | SUCCESS => {"ping": "pong"}

$ ansible -i inventory/hosts.ini web1 \
    -m ansible.builtin.package -a 'name=nginx state=present' -b
  install nginx, as root
web1 | CHANGED => { … }

-i inventory/hosts.ini

the file that says which machines exist and what they are called. Without it Ansible has no idea what web1 means.

-m

the module: the unit of work. ping, package, copy, service — around a thousand of them ship in collections.

-a

the module's arguments, as key=value pairs here and as YAML everywhere else.

-b

become: run it as root, via sudo. Without it you are the deploy user and the install fails.

A module plus its arguments plus a host is the whole unit. Nothing is installed on web1 to make this work — Ansible speaks SSH and Python.

03

Write it down

The same thing, in a file. A TASK is a name, a module and the module's arguments — the three things you just typed, one per line. A task cannot stand alone, so it arrives wrapped in a PLAY, and --limit web1 keeps it to the one machine for now.

$ ansible-playbook -i inventory/hosts.ini site.yml --limit web1
  the file, against one host

- name:

a label. It is what the output prints and nothing else; the task works without it. Without it the output prints the module name, and a run becomes much harder to read.

ansible.builtin.package:

the module, fully qualified — namespace, collection, module. ansible.builtin ships with Ansible; others come from Galaxy.

state: present

an assertion about how the host should end up, not a command to run. This is the difference that makes the next step possible.

hosts:

which machines. A task cannot stand on its own, so it arrives inside a play, and the play names its targets.

become:

the -b from step 2, set once for every task in the play instead of per command.

tasks:

everything below here runs, in order, against every host the play named.

Gathering Facts

a task you did not write. Every play opens by running setup against each host to learn ~1,200 facts about it. Step 7 is where that pays off. gather_facts: false turns it off — and anything reading a fact then breaks.

A task is a module call with a label, and it lives in a play. The YAML maps one-to-one onto the command line you just used.

04

Run it twice

Run the same file again, immediately. Nothing is installed a second time — the module looks at the host, finds nginx already present, and says so. That property has a name, and it is the reason Ansible is safe to run on a schedule, from CI, or by someone who does not know what the last person did.

$ ansible-playbook -i inventory/hosts.ini site.yml --limit web1
  the same command, a second time

changed

the module altered the host.

ok

the module ran, checked, and found there was nothing to do.

PLAY [Web tier] ******************************
 
TASK [Gathering Facts] ***********************
ok: [web1]
 
TASK [Install nginx] *************************
changed: [web1]
 
PLAY RECAP ***********************************
web1    : ok=2    changed=1    unreachable=0   failed=0   skipped=0

PLAY [Web tier] ******************************
 
TASK [Gathering Facts] ***********************
ok: [web1]
 
TASK [Install nginx] *************************
ok: [web1]
 
PLAY RECAP ***********************************
web1    : ok=2    changed=0    unreachable=0   failed=0   skipped=0

Idempotent: running it twice is the same as running it once. You get that free from state: modules and lose it the moment you reach for shell:.

05

More than one machine

Drop the --limit. Nothing in the file changes — it already said hosts: webservers, and that one line is the fan-out. The task you wrote once now runs against three machines and comes back with three different answers.

$ ansible-playbook -i inventory/hosts.ini site.yml
  no --limit: every host in the group

hosts: webservers

a group from the inventory. Ansible expands it to web1, web2 and web3 and runs every task against all of them. --limit narrows it at the command line without editing the file, which is what the last two steps were doing.

web2 says ok

the same task, the same file, a different answer — because web2 already had nginx. A verdict describes the host, not the task.

Play = hosts + tasks. The same task, the same file, three machines — and three different answers, because web2 already had nginx.

06

More than one task

Add a second task. Tasks run top to bottom, and every host finishes a task before any host starts the next — so the grid grows downwards, a row at a time.

state: started

running now.

enabled: true

running after a reboot. Two independent assertions in one task, and one changed covering both.

Order is the file's order. A play is a column of task rows, each run against every host.

07

Hosts differ

web3 is Debian; the other two are Red Hat. Ansible already knows, because of the facts it gathered — so a task can be given a condition, and a file can be given a variable instead of a number.

vars:

names you set once and use everywhere below. nginx_port: 8080.

{{ nginx_port }}

Jinja2. It is rendered on YOUR machine, before anything is sent — the host never sees the braces.

mode: "0644"

quoted, always. Unquoted, YAML reads 0644 as an octal number and the file lands with the wrong permissions.

when:

a condition, tested on your machine against the facts. False means the task is skipped and no connection is opened at all.

template:

renders a .j2 file locally, compares it with what is on the host, and transfers only if they differ.

Facts describe the host; variables describe your intent; when joins them. One file, three different runs.

08

Repeat, capture, look

Three things you will reach for constantly, none of which this particular file needs. They are shown here as they are used, not folded into site.yml — a guide that teaches you to write code you would delete is worse than one that says not here.

$ ansible-playbook -i inventory/hosts.ini site.yml --limit web1 -v
  the same run, with every module's reply printed
changed: [web1] => {"changed": true, "rc": 0, "results": [...]}

-v

verbosity. -v prints each module's JSON reply, -vv adds the task's file and line, -vvv adds the SSH commands themselves. This is the fastest way to find out why something said changed.

- name: Install the tools
  ansible.builtin.package:
    name: "{{ item }}"
    state: present
  loop:
    - nginx
    - curl
    - jq

TASK [Install the tools] ****************
changed: [web1] => (item=nginx)
ok: [web1] => (item=curl)
changed: [web1] => (item=jq)

- name: Check the config
  ansible.builtin.command: nginx -t
  register: result
  changed_when: false

- name: Show it
  ansible.builtin.debug:
    var: result.stdout

TASK [Show it] **************************
ok: [web1] => {
    "result.stdout": "syntax is ok"
}

- name: Try the fast path
  block:
    - ansible.builtin.command: /usr/local/bin/fastpath
  rescue:
    - ansible.builtin.command: /usr/local/bin/slowpath
  always:
    - ansible.builtin.file:
        path: /tmp/lock
        state: absent

TASK [command] **************************
fatal: [web1]: FAILED! => { … }
 
TASK [command] **************************
changed: [web1]

loop repeats, register captures, debug shows, block recovers. With -v these are the whole debugging loop.

09

React to a change

nginx needs reloading when its config changes — and only then. A HANDLER is a task that does nothing until something notifies it, and then runs once, at the end of the play.

handlers:

tasks defined but not run. They sit in the play alongside tasks:.

notify: Reload nginx

queues the handler by name — but only if this task reported changed. An ok task notifies nothing. That is why web3, whose config already matched, does not reload.

Notified on changed, de-duplicated, and flushed at the end of the play — not where you wrote it.

10

A second play, and running it for real

The database is a different group with different work, so it is a different play. Plays run one after another, always. That is the whole file — and this is how you actually set it going.

$ ansible-playbook -i inventory/hosts.ini site.yml
  the whole thing
$ ansible-playbook -i inventory/hosts.ini site.yml --check --diff
  change nothing; report what WOULD change, and show the diffs
$ ansible-playbook -i inventory/hosts.ini site.yml --limit web1
  one host out of the group
$ ansible-playbook -i inventory/hosts.ini site.yml --tags nginx
  only tasks carrying that tag
$ ansible-playbook -i inventory/hosts.ini site.yml --start-at-task 'Open the port'
  resume after a failure, without redoing the slow part
$ ansible-doc ansible.builtin.service
  every argument the module takes, with examples, offline

--check

dry run. Every module is asked what it would do. command and shell are skipped, because they cannot predict.

--limit

narrows the hosts without editing the inventory. The first thing to reach for when something goes wrong.

That is the file the rest of this page runs. Below, it stops being source and starts being nineteen modules crossing four SSH connections.