Understanding Ansible¶
Ansible configures servers over SSH. You describe the desired state once, for example "nginx is installed and serves this page", and Ansible brings any number of servers to that state. It doesn't need an agent on the servers: SSH access and Python are enough.
Control node and managed servers¶
tuxdex-srv (control node)
ansible, playbooks, inventory
│ SSH
┌────────┴────────┐
▼ ▼
web01 web02
192.0.2.21 192.0.2.22
| Term | Meaning |
|---|---|
| Control node | The machine where Ansible is installed and where you run it |
| Managed node | A server Ansible configures; it needs SSH and Python 3 |
| Inventory | The list of servers, sorted into groups |
| Module | A unit of work, such as apt, copy, service or user |
| Task | One call of a module with its parameters |
| Playbook | A YAML file with tasks for groups of servers |
| Role | A reusable bundle of tasks, files, templates and variables |
| Handler | A task that only runs when another task changed something, such as reloading nginx |
What you need to install¶
Ansible is only installed on the control node. The managed servers need nothing but an
SSH server, Python 3 and your SSH key, see ssh-copy-id.
| Debian | Ubuntu | RHEL | Arch | |
|---|---|---|---|---|
| Ansible | sudo apt install ansible |
sudo apt install ansible |
sudo dnf install ansible-core (full ansible from EPEL) |
sudo pacman -S ansible |
| ansible-lint | sudo apt install ansible-lint |
sudo apt install ansible-lint |
pipx install ansible-lint |
sudo pacman -S ansible-lint |
ansible is ansible-core plus a large set of collections such as community.general.
With ansible-core alone, you install the collections you need with
ansible-galaxy. On any distribution, pipx install --include-deps ansible
gets the newest version.
The inventory¶
~/ansible/inventory.ini:
[web]
web01 ansible_host=192.0.2.21
web02 ansible_host=192.0.2.22
[db]
[production:children]
web
Groups like web let you address several servers at once. Variables for a group go into
group_vars/web.yml, for a single server into host_vars/web01.yml.
A playbook¶
~/ansible/site.yml installs nginx on all web servers and puts a status page in place:
- name: Set up web servers
hosts: web
become: true
tasks:
- name: Install nginx
ansible.builtin.apt:
name: nginx
state: present
update_cache: true
cache_valid_time: 3600
tags: packages
- name: Deploy status page
ansible.builtin.copy:
content: "<h1>{{ inventory_hostname }}: all systems operational</h1>\n"
dest: /var/www/html/index.html
mode: "0644"
notify: Reload nginx
handlers:
- name: Reload nginx
ansible.builtin.service:
name: nginx
state: reloaded
become: true runs the tasks with sudo. Run it with
ansible-playbook.
Idempotency¶
Modules describe a state, not an action. state: present means "nginx must be installed",
not "install nginx". If it already is, nothing happens and the task reports ok instead of
changed. That's why you can run a playbook as often as you like: the second run changes
nothing.
A project directory¶
~/ansible/
├── ansible.cfg # settings for this project
├── inventory.ini # servers and groups
├── site.yml # main playbook
├── group_vars/
│ ├── web.yml # variables for the group web
│ └── secrets.yml # passwords, encrypted with ansible-vault
└── roles/
└── nginx/ # a role, created with ansible-galaxy role init
~/ansible/ansible.cfg:
[defaults]
inventory = inventory.ini
remote_user = nox
interpreter_python = auto_silent
With this file, you no longer need -i inventory.ini on every command, as long as you run
Ansible in this directory. See ansible-config.
Keep the project in Git
An Ansible project belongs in a Git repository, see the chapter Git. Then every change to your servers is documented, reviewable and can be undone.
Use modules, not shell commands
ansible.builtin.shell: apt install nginx works, but it reports changed on every run
and can't be checked with --check. A module like ansible.builtin.apt knows the
current state and only acts when needed.