Ansible: inventory and ad-hoc commands

The idea of configuration management

Terraform creates servers. Something must then install nginx, copy config files, create users and start services, on every server, the same way. Doing this by hand over SSH on 50 servers is slow and each server ends up a little different. Configuration management tools describe the desired state ("nginx is installed and running, this file has this content") and make every server match it.

How Ansible works

• Control node: the machine where Ansible is installed and where you run commands (your laptop, a CI runner or a jump server). It must be Linux or macOS; on Windows use WSL.
• Managed nodes: the servers Ansible configures. Nothing extra is installed on them. Linux nodes need SSH and Python. Windows nodes are reached with WinRM or PSRP instead of SSH.
• Inventory: a file that lists the managed nodes, in groups.
• Modules: small programs for one job (install a package, copy a file, start a service). Ansible copies the module to the node over SSH, runs it and removes it.
• Push model: the control node pushes changes when you run it. Chef and Puppet traditionally use agents that pull from a server.

Because there is no agent to install or patch, Ansible is easy to start with. It is owned by Red Hat and is open source. You install it with pip install ansible (or your OS package manager). The ansible package includes ansible-core plus many collections of modules.

The inventory

An inventory lists hosts (servers) and groups them. INI format is short and common. A host line can carry variables such as ansible_host (the real address) and ansible_user (the SSH user). [group:vars] sets variables for a whole group, and [group:children] makes a group of groups. Two groups always exist: all (every host) and ungrouped (hosts in no other group).

# inventory.ini
[web]
web1.college.edu ansible_host=10.0.1.11
web2.college.edu ansible_host=10.0.1.12

[db]
db1.college.edu ansible_host=10.0.2.21

[prod:children]
web
db

[web:vars]
ansible_user=deploy

all:
  children:
    web:
      hosts:
        web1.college.edu:
          ansible_host: 10.0.1.11
        web2.college.edu:
          ansible_host: 10.0.1.12
      vars:
        ansible_user: deploy
    db:
      hosts:
        db1.college.edu:
          ansible_host: 10.0.2.21

ansible-inventory -i inventory.ini --graph   # show groups and hosts as a tree
ansible-inventory -i inventory.ini --list    # show everything as JSON

Ad-hoc commands

An ad-hoc command runs one module on a group of hosts, straight from the command line. It is useful for quick checks and one-off jobs. For anything you will repeat, write a playbook (next lesson).

ansible all -i inventory.ini -m ansible.builtin.ping
ansible web -i inventory.ini -m ansible.builtin.apt -a "name=nginx state=present update_cache=true" --become
ansible web -i inventory.ini -m ansible.builtin.service -a "name=nginx state=restarted" --become
ansible db -i inventory.ini -m ansible.builtin.command -a "df -h"

The ping module is not a network ping. It logs in over SSH, checks that Python works, and answers "pong". Write modules with their fully qualified collection name (FQCN), such as ansible.builtin.apt: the collection (ansible.builtin) plus the module name. Short names like apt still work, but FQCNs avoid clashes between collections.

ok, changed and idempotency

Each module checks the current state first. If nginx is already installed, the apt module does nothing and reports ok (green). If it had to install it, it reports changed (yellow). Failures are red. Run the same command twice: the second run should be all ok. This idempotency is what makes Ansible safe to rerun.

web1.college.edu | CHANGED => { "changed": true, ... }
web2.college.edu | SUCCESS => { "changed": false, ... }

ansible.cfg

ansible.cfg holds settings so you do not type them every time, for example the inventory path and the remote user. Ansible looks for it in this order: the ANSIBLE_CONFIG environment variable, ansible.cfg in the current folder, ~/.ansible.cfg, and /etc/ansible/ansible.cfg.

[defaults]
inventory = ./inventory.ini
remote_user = deploy

Common mistakes