Ansible

01The idea: desired state over SSH

Imagine writing a checklist for setting up a server: install nginx, copy the config, open port 443, start the service. Ansible turns that checklist into code. The control node, your laptop or a CI runner with Ansible installed, connects to managed nodes over SSH, copies small Python modules, runs them and removes them. Each task calls a module such as apt, copy, template, user or service, and describes the end state (state: present, state: started) rather than the commands to get there. The module checks the current state first and only changes what differs, reporting ok or changed. That property, idempotency, means you can run the same playbook every day as a drift check. Ansible is distributed as ansible-core (the engine and built-in modules) plus collections, packages of modules for clouds, databases and network devices, bundled together in the ansible community package.

• Control node: where Ansible runs. Managed nodes: the servers.
• Module: a unit of work (apt, template, service).
• Idempotent: second run reports ok, not changed.

02Install, inventory and ad-hoc commands

Install Ansible on the control node with pipx or pip into its own environment, which avoids conflicts with system Python. The inventory lists managed hosts and groups them, in INI or YAML. Groups let you target web servers or databases separately, and group_vars/ and host_vars/ folders hold variables per group or host. Before writing playbooks, test connectivity with ad-hoc commands: one-off module calls from the command line. ansible all -m ping does not use ICMP; it logs in over SSH and checks Python. Use SSH keys and a non-root user with sudo; Ansible's become: true escalates privileges for tasks that need it. Keep ansible.cfg in the project to set the inventory path and sensible defaults.

1# install on the control node
2pipx install --include-deps ansible
3 
4# inventory.yml
5all:
6  children:
7    web:
8      hosts:
9        web1: { ansible_host: 203.0.113.10 }
10        web2: { ansible_host: 203.0.113.11 }
11  vars:
12    ansible_user: your_user
13 
14# test connectivity and gather facts
15ansible -i inventory.yml all -m ping
16ansible -i inventory.yml web -m ansible.builtin.setup -a "filter=ansible_distribution*"

03Your first playbook

A playbook is a list of plays; each play targets hosts and runs tasks in order. The example installs nginx on the web group, deploys a site configuration from a Jinja2 template, and makes sure the service runs. The notify line triggers a handler only when the template actually changed, so nginx reloads once at the end of the play instead of on every run. Always use fully qualified module names such as ansible.builtin.apt, which make it clear which collection a module comes from. Run it with --check --diff first to see what would change without changing anything, then for real. A second real run should show changed=0; if it does not, a task is not idempotent and should be fixed.

1- name: Configure web servers
2  hosts: web
3  become: true
4  tasks:
5    - name: Install nginx
6      ansible.builtin.apt:
7        name: nginx
8        state: present
9        update_cache: true
10    - name: Deploy site config
11      ansible.builtin.template:
12        src: templates/site.conf.j2
13        dest: /etc/nginx/sites-available/default
14        mode: "0644"
15      notify: Reload nginx
16    - name: Ensure nginx is running
17      ansible.builtin.service: { name: nginx, state: started, enabled: true }
18  handlers:
19    - name: Reload nginx
20      ansible.builtin.service: { name: nginx, state: reloaded }

04Variables, templates and secrets

Variables make one playbook work for many environments: the same role configures staging and production with different values from group_vars/staging.yml and group_vars/production.yml. Templates use Jinja2 syntax, {{ variable }} and simple loops or conditions, to render configuration files from those variables. Facts are variables Ansible gathers automatically from each host, such as the OS version, memory and IP addresses, useful for conditions like when: ansible_distribution == 'Ubuntu'. Variable precedence has many levels; keep it simple by using role defaults for sane values and group_vars for environment overrides. For secrets, Ansible Vault encrypts files or single values with a password, so they can live in Git safely. In CI, supply the vault password from the CI secret store, or fetch secrets at run time from a manager such as HashiCorp Vault with a lookup plugin.

1# group_vars/production/vars.yml
2app_domain: example.com
3app_workers: 4
4db_password: "{{ vault_db_password }}"
5 
6# group_vars/production/vault.yml (encrypted)
7# ansible-vault create group_vars/production/vault.yml
8# vault_db_password: change-me
9 
10# run with the vault password
11ansible-playbook -i inventory.yml site.yml --ask-vault-pass

05Roles and collections: structure that scales

When playbooks grow, split them into roles: a standard folder layout with tasks, handlers, templates, files, defaults and meta. A role does one thing well, such as nginx, postgres or a base hardening baseline, and a site playbook composes roles per host group. ansible-galaxy role init creates the skeleton. Collections package roles, modules and plugins together under a namespace, and you install them from Ansible Galaxy or a private hub with a requirements.yml pinned to versions, the way you would pin npm packages. Test roles with Molecule, which starts a container or VM, applies the role, runs it again to check idempotency and verifies the result. Lint with ansible-lint in CI to catch deprecated syntax, missing names and risky patterns.

1# requirements.yml
2collections:
3  - name: community.general
4    version: ">=10.0.0,<11.0.0"
5  - name: ansible.posix
6    version: ">=2.0.0"
7 
8# site.yml
9- hosts: web
10  become: true
11  roles:
12    - base_hardening
13    - nginx
14 
15# ansible-galaxy collection install -r requirements.yml

06How a task actually executes

For each task, Ansible renders the module arguments with Jinja2 on the control node, packages the module code (AnsiballZ) and sends it over SSH, then runs it with the remote Python and reads JSON back. By default it does this for forks hosts at a time (default 5) under the linear strategy, where every host finishes a task before any host starts the next. Performance tuning matters at scale: raise forks, enable pipelining in ansible.cfg (it removes extra SSH round-trips, but requires that sudo does not demand a TTY), keep SSH ControlPersist multiplexing on, and turn off or cache fact gathering when you do not need facts. The free strategy lets fast hosts run ahead. Long tasks can run asynchronously with async and poll so connections are not held open.

1# ansible.cfg
2[defaults]
3inventory = inventory.yml
4forks = 25
5gathering = smart
6fact_caching = jsonfile
7fact_caching_connection = .ansible_facts
8fact_caching_timeout = 3600
9 
10[ssh_connection]
11pipelining = True
12ssh_args = -o ControlMaster=auto -o ControlPersist=60s

07Rolling updates with serial and health checks

Production changes should never hit every host at once. serial accepts a number, a percentage or a list such as [1, 5, "25%"], which gives you a canary host, then a small batch, then larger ones. delegate_to runs a task on another machine, typically to take the current host out of a load balancer. Combined with until and retries, a health check waits for the service to become healthy before moving on. max_fail_percentage aborts the play when too many hosts in a batch fail, which stops a bad release from spreading. any_errors_fatal stops everything at the first failure, useful for database clusters where partial changes are dangerous.

1- hosts: web
2  become: true
3  serial: [1, 5, "25%"]
4  max_fail_percentage: 0
5  tasks:
6    - name: Deploy new release
7      ansible.builtin.include_role: { name: app_release }
8    - name: Wait until healthy
9      ansible.builtin.uri:
10        url: "http://{{ ansible_host }}:8080/healthz"
11        status_code: 200
12      register: health
13      until: health.status == 200
14      retries: 20
15      delay: 3
16      delegate_to: localhost

08Dynamic inventory, AWX and Execution Environments

Static inventory files go stale in the cloud. Inventory plugins such as amazon.aws.aws_ec2, azure.azcollection.azure_rm or google.cloud.gcp_compute query the provider and build groups from tags, so a server tagged role=web appears in the web group automatically. To run Ansible as a shared service rather than from laptops, AWX (the open-source upstream of Red Hat Ansible Automation Platform) provides a web UI, role-based access, credential storage, schedules, an API and audit logs. Execution Environments are container images that bundle ansible-core, collections and Python dependencies, built with ansible-builder and run with ansible-navigator or AWX. They fix the classic "works on my control node" problem by making the automation runtime as reproducible as the application images it deploys.