Ansible for beginners

TASK[Set up your lab]

5 minutes if you did the setup appendix already

$ cd ~/ansible-lab
$ docker compose up -d
$ ansible all -m ping -k      # SSH password: ansible

TASK[What is Ansible?]

12 minutes

One server is easy. A hundred is not.

$ ssh server-01
$ sudo apt install nginx
$ sudo vi /etc/nginx/nginx.conf
$ sudo systemctl restart nginx
# ...and again for server-02 to server-100

- name: Web servers
  hosts: webservers    # 1 or 1000 hosts
  become: true
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx

Definition

Ansible is an open-source, agentless automation tool. It configures systems, deploys software and orchestrates IT work using readable YAML files, connecting over SSH to Linux and over WinRM or SSH to Windows.

Four ideas behind Ansible

Infrastructure as Code

Servers are described in text files kept in Git, so every change is reviewed, versioned and repeatable.

Configuration management

Keep many machines in a known, consistent state: packages, files, users and services.

Idempotency

Running the same playbook twice gives the same result. If nothing has drifted, the second run changes nothing.

Declarative

You say what you want (“nginx is present and running”). The module works out how to get there.

What people automate with it

TASK[Ansible vs Chef vs Puppet vs SaltStack]

10 minutes

Push vs pull

TASK[Why Ansible?]

5 minutes

Simple

YAML reads like a checklist. Most people are productive on day one.

Agentless

Only SSH and Python on targets. Nothing extra to patch, monitor or secure.

Idempotent

Safe to re-run; only what is different gets changed.

Batteries included

Thousands of modules and collections on Ansible Galaxy.

Works everywhere

Linux, Windows, cloud, containers and network gear.

Big community

A common DevOps skill in job listings, backed by Red Hat.

TASK[Architecture]

12 minutes

What happens when a task runs

1. ReadParse ansible.cfg, the inventory, the playbook and variables.
2. ConnectOpen SSH to each host, several at a time (forks, default 5; the lab uses 10).
3. CopySend the module, a small Python program, to a temporary folder on the host.
4. ExecuteRun it. The module compares the current state with the desired state.
5. ReturnThe module replies with JSON: ok, changed or failed.
6. Clean upRemove the temporary files and move on to the next task.

$ ansible-inventory --graph
$ ansible-config dump --only-changed
$ ansible web1 -m ping -vvv      # watch connect, copy, execute, return

TASK[Terminologies]

10 minutes

The building blocks

Control node

The machine Ansible is installed on and run from. Linux or macOS; on Windows, use WSL.

Managed node (host)

Any machine Ansible configures. Needs SSH and Python (Linux) or WinRM (Windows).

Inventory

The list of managed nodes, organised into groups. INI or YAML, static or dynamic.

Module

A unit of work Ansible sends to a host, such as apt, copy, service or user.

Task

One call to a module with arguments, plus a descriptive name.

Play

Maps a group of hosts to a list of tasks.

Playbook

A YAML file containing one or more plays.

The power features

Variables

Values that differ per host, group or environment, such as http_port: 80.

Facts

Information Ansible discovers about each host (OS, IP, memory) using the setup module.

Handlers

Tasks that run only when another task notifies them of a change, like restarting nginx.

Templates

Jinja2 files (.j2) filled in with variables to produce real config files.

Roles

A standard folder layout that packages tasks, handlers, templates and variables for reuse.

Collections

The distribution format for modules, roles and plugins, such as ansible.posix.

Ansible Galaxy

The public hub for sharing roles and collections.

Vault

Built-in encryption for passwords, keys and other secrets.

Inventory: telling Ansible which hosts exist

[webservers]
web1 ansible_host=127.0.0.1 ansible_port=2221
web2 ansible_host=127.0.0.1 ansible_port=2222

[dbservers]
db1  ansible_host=127.0.0.1 ansible_port=2223

[lab:children]     # a group of groups
webservers
dbservers

all:
  children:
    lab:
      children:
        webservers:
          hosts:
            web1:
            web2:
        dbservers:
          hosts:
            db1:

Where variables live

# inventory/group_vars/webservers.yml
http_port: 80
page_title: "Hello from Ansible"

# inventory/host_vars/db1.yml
server_role: database

# use it anywhere with Jinja2
msg: "Port is {{ http_port }}"

TASK[Playbook structure]

20 minutes, including hands-on

YAML in five minutes

---                    # optional document start
name: Alice            # key: value (a mapping)
is_admin: true         # booleans: true / false
packages:              # a list
  - nginx
  - curl
user:                  # a nested mapping
  name: bob
  shell: /bin/bash
inline_list: [a, b, c]
message: "Quote values that contain {{ vars }} or colons"
script: |              # keep line breaks
  line one
  line two

Playbook, play, task, module

Playbook

A YAML file holding an ordered list of plays.

Play

Targets a group of hosts and sets options such as become, vars and gather_facts.

Task

One step. It runs on every host in the play before the next task starts.

Module

The code that does the work for a task.

Anatomy of a playbook

---
- name: Install and configure nginx    # play name
  hosts: webservers                    # which inventory group
  become: true                         # run as root via sudo
  vars:
    owner_team: "Ansible learners"

  tasks:
    - name: Install nginx
      ansible.builtin.apt:              # module, written with its full name
        name: nginx                     # module arguments describe the state
        state: present
        update_cache: true

    - name: Deploy the home page from a template
      ansible.builtin.template:
        src: templates/index.html.j2
        dest: /var/www/html/index.html
        mode: "0644"
      notify: Restart nginx            # triggers the handler below

    - name: Ensure nginx is running
      ansible.builtin.service:
        name: nginx
        state: started

  handlers:
    - name: Restart nginx               # runs once, at the end, only if notified
      ansible.builtin.service:
        name: nginx
        state: restarted

$ ansible-playbook playbooks/03_webserver.yml --check    # dry run
$ ansible-playbook playbooks/03_webserver.yml            # for real
$ ansible-playbook playbooks/03_webserver.yml            # again: changed=0

Loops, conditionals and register

- name: Install packages                    # loop: repeat for each item
  ansible.builtin.apt:
    name: "{{ item }}"
  loop: [curl, tree, vim-tiny]

- name: Only on Debian-family systems       # when: run only if true
  ansible.builtin.debug:
    msg: "apt is the right module here"
  when: ansible_facts['os_family'] == "Debian"

- name: Read uptime                         # register: save the result
  ansible.builtin.command: uptime
  register: up
  changed_when: false                       # reading never changes the server

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

Roles: organise playbooks for reuse

ansible-lab/
├── ansible.cfg
├── inventory/
│   ├── wsl.ini
│   ├── group_vars/
│   └── host_vars/
├── playbooks/site.yml
└── roles/
    └── nginx/
        ├── tasks/main.yml
        ├── handlers/main.yml
        ├── templates/index.html.j2
        ├── files/
        ├── vars/main.yml
        ├── defaults/main.yml
        └── meta/main.yml

- hosts: webservers
  become: true
  roles:
    - nginx

Reading the output

PLAY RECAP *********************************************
web1 : ok=5  changed=0  unreachable=0  failed=0  skipped=0
web2 : ok=6  changed=3  unreachable=0  failed=0  skipped=0

TASK[Authentication mechanism]

10 minutes, including hands-on

1. How do I log in?

SSH password (-k, needs sshpass) or, preferably, an SSH key pair. Windows uses WinRM (NTLM, Kerberos or certificates) or SSH. ansible_user or remote_user sets the login name.

2. How do I get root?

Privilege escalation with become: true (sudo by default), become_user to switch to another account, and -K to prompt for the sudo password.

3. How do I protect secrets?

Ansible Vault encrypts files with AES-256. no_log: true hides values in output. Larger teams often use HashiCorp Vault or CyberArk.

From password to SSH keys

1. Create a key pair on the control nodessh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
2. First contact with a passwordansible all -m ping -k and type ansible
3. Copy the public key to every nodeansible-playbook playbooks/06_ssh_keys.yml -k
4. Log in without a password from now onansible all -m ping

- name: Distribute the control node's public key
  hosts: all
  gather_facts: false
  tasks:
    - name: Add public key to ~ansible/.ssh/authorized_keys
      ansible.posix.authorized_key:
        user: ansible
        state: present
        key: "{{ lookup('ansible.builtin.file', lookup('ansible.builtin.env', 'HOME') + '/.ssh/id_ed25519.pub') }}"

Privilege escalation

- hosts: dbservers
  become: true                       # the whole play runs as root
  tasks:
    - name: Create a database as the postgres user
      ansible.builtin.command: createdb app
      become_user: postgres          # just this task

Ansible Vault

$ cp vault/secrets.example.yml vault/secrets.yml
$ ansible-vault encrypt vault/secrets.yml       # choose a vault password
$ cat vault/secrets.yml                          # $ANSIBLE_VAULT;1.1;AES256 ...
$ ansible-vault view vault/secrets.yml
$ ansible-vault edit vault/secrets.yml
$ ansible-playbook playbooks/07_vault.yml --ask-vault-pass

TASK[Executing Ansible modules]

10 minutes, hands-on

$ ansible all -m ansible.builtin.command -a "hostname"
$ ansible all -m ansible.builtin.shell -a "df -h | grep /"
$ ansible web1 -m ansible.builtin.setup -a "filter=ansible_distribution*"
$ ansible webservers -b -m ansible.builtin.apt -a "name=tree state=present update_cache=true"
$ ansible all -b -m ansible.builtin.copy -a "content='hello' dest=/tmp/hello.txt"
$ ansible dbservers -b -m ansible.builtin.user -a "name=carol state=present"
$ ansible webservers -b -m ansible.builtin.service -a "name=nginx state=restarted"
$ ansible 'webservers:!web2' -m ping       # all web servers except web2

command, shell or raw?

TASK[Modules]

8 minutes

Packages

apt, dnf, yum, package, pip

Files

copy, file, template, lineinfile, fetch

Services

service, systemd, cron

Users and security

user, group, authorized_key, firewalld

Commands

command, shell, script, raw

Source and network

git, get_url, uri, unarchive

Cloud

amazon.aws, azure.azcollection, google.cloud collections

Windows

win_package, win_service, win_copy

The ten you will use most

Look modules up instead of memorising them

$ ansible-doc -l | grep -i apt            # list and search modules
$ ansible-doc ansible.builtin.copy        # full documentation with examples
$ ansible-doc -s ansible.builtin.user     # short snippet to paste into a task
$ ansible-galaxy collection list          # installed collections
$ ansible-galaxy collection install community.general

TASK[Best practices]

8 minutes

Name every task

Clear names make output and failures easy to read.

Modules over shell

Dedicated modules are idempotent; shell commands rarely are.

Use FQCN

ansible.builtin.copy, never a bare copy.

Structure with roles

Small roles with one job each, reused across playbooks.

Separate data from code

Values in group_vars and host_vars; logic in tasks.

Keep secrets in Vault

Never commit plain-text passwords or keys.

Check before you change

--syntax-check, --check --diff and ansible-lint.

Least privilege

Use become only on tasks that need root.

Version everything

Git, code review, and CI that runs ansible-lint.

Same goal, better task

- shell: apt-get install -y nginx

- shell: echo "ServerName x" >> /etc/app.conf

- copy: src=db.conf dest=/etc/
  # the password is inside db.conf, in Git

- hosts: all
  become: true      # every task as root

- name: Install nginx
  ansible.builtin.apt:
    name: nginx
    state: present

- name: Set ServerName once
  ansible.builtin.lineinfile:
    path: /etc/app.conf
    line: "ServerName x"
# secrets in Vault, become per task

$ ansible-lint playbooks roles

TASK[Recap and quiz]

5 minutes

Ansible

Agentless, YAML-based, push-style automation over SSH or WinRM.

Versus others

Chef and Puppet use agents and pull; Salt uses an event bus.

Architecture

Control node with inventory, playbooks and modules, connecting to managed nodes.

Playbooks

Playbook, plays, tasks, modules; plus handlers, variables and roles.

Authentication

SSH keys to connect, become for root, Vault for secrets.

Modules

Ad-hoc for one-offs; dedicated modules over shell; look them up with ansible-doc.

Quick quiz

Keep going after today

TASK[Appendix: set up the lab on Windows]

Do this first, about 40 minutes the first time. Full troubleshooting is in the README.

1. Check the prerequisitesIn PowerShell, from the lab folder: powershell -ExecutionPolicy Bypass -File .\scripts\check-prereqs.ps1
2. Install WSL2 with UbuntuPowerShell as Administrator: wsl --install -d Ubuntu-24.04, reboot, then create your Linux user.
3. Install Docker DesktopKeep the WSL 2 backend. In Settings, Resources, WSL integration, turn on Ubuntu-24.04. Test in Ubuntu with docker run --rm hello-world.
4. Install VS Code (recommended)Add the WSL, Ansible and YAML extensions, then run code . from the lab folder.
5. Get the lab into your Linux home foldergit clone https://github.com/YOUR-USER/ansible-lab.git ~/ansible-lab
   Do not work from /mnt/c/…: Windows folders look world-writable to Linux, so Ansible ignores ansible.cfg there.
6. Install Ansiblecd ~/ansible-lab && bash scripts/setup-wsl.sh && source ~/.bashrc
7. Start the serversdocker compose up -d --build, then docker ps should list web1, web2, db1 and control.
8. Smoke testansible all -m ping -k with the password ansible. Three green lines and you are done.

Common problems