Ansible for beginners: your first playbook, step by step

If you have to make the same change on three servers, doing it by hand over SSH is still manageable. With thirty it isn’t – and after a while you can’t remember what you changed on which machine. This is what Ansible is for: you describe in a simple YAML file what state the servers should be in, and Ansible connects over SSH and makes sure they are.

In this article we introduce Ansible for beginners: we install it, write the first inventory, test the connection, and finally write a playbook that installs and configures nginx on several servers.

What is Ansible, and how is it different?

Ansible is an open-source configuration management and automation tool, developed by Red Hat together with the community. A few things that make it a good choice for beginners as well:

  • No agent. You don’t need to install anything on the managed servers; SSH and Python are enough. Ansible runs from a single machine, the control node, which can be your own laptop.
  • Declarative. You don’t write “run the apt install nginx command”, but “nginx should be installed”. If it is already installed, Ansible does nothing.
  • Idempotent. The same playbook can be run any number of times, and it always produces the same state. So you can safely run it regularly, to keep manual “quick fixes” from making the servers drift.

Two terms are worth clarifying at the start: ansible-core is the engine itself (the command-line tools and the built-in modules), and the ansible package is ansible-core plus a large selection of community collections, such as community.general or ansible.posix. The latest versions at the moment are ansible-core 2.20 (November 2025) and Ansible 13, which is built on it.

Installation

ansible-core 2.20 requires at least Python 3.12 on the control node, and Python 3.9 or newer on the managed servers. On Debian 13 and Ubuntu 24.04, the simplest way is with pipx, as recommended by the official documentation:

sudo apt install pipx
pipx ensurepath
pipx install --include-deps ansible
ansible --version

The distribution’s own package (apt install ansible) also works, but it is often a version or two behind. That is fine for learning; but if you work in a team, everyone should use the same version.

The inventory: what are we managing?

The inventory is the file that lists the managed servers, organised into groups. Its simplest form is INI:

# inventory.ini
[web]
web1.example.com
web2.example.com

[db]
db1.example.com ansible_user=admin

[all:vars]
ansible_user=deploy

You can refer to the groups later: a task can run only on the web group, only on db, or on all machines (all).

Ansible logs in over SSH, so you need key-based login from the control node to the servers. If you don’t have that yet, we described how to create and install a key in the knowledge base of our hosting brand, aWh.

Test the connection with the ping module (this isn’t a network ping, but a small piece of Python code that checks whether Ansible can work on the machine):

ansible all -i inventory.ini -m ansible.builtin.ping

If every machine answers "ping": "pong", you are ready.

Ad hoc commands

For one-off tasks you don’t need a playbook. For example, the free disk space of all web servers:

ansible web -i inventory.ini -a "df -h /"

Or updating a package with administrator privileges (-b, that is, become):

ansible web -i inventory.ini -b -m ansible.builtin.apt -a "name=openssl state=latest update_cache=true"

Knowing the command line comes in handy here too; we collected the most common commands in the aWh knowledge base.

The first playbook

A playbook is a YAML file made up of one or more plays; each play says which tasks to run on which machines. The example below installs nginx on every machine in the web group, puts up a simple landing page, and makes sure the service is running:

# webserver.yml
- name: Configure web servers
  hosts: web
  become: true

  vars:
    site_title: "Welcome to {{ inventory_hostname }}"

  tasks:
    - name: Nginx is installed
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true
        cache_valid_time: 3600

    - name: The landing page is in place
      ansible.builtin.template:
        src: templates/index.html.j2
        dest: /var/www/html/index.html
        owner: root
        group: root
        mode: "0644"

    - name: The nginx configuration is in place
      ansible.builtin.copy:
        src: files/default.conf
        dest: /etc/nginx/sites-available/default
        mode: "0644"
      notify: Reload nginx

    - name: Nginx is running and starts automatically
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

  handlers:
    - name: Reload nginx
      ansible.builtin.service:
        name: nginx
        state: reloaded

The template (templates/index.html.j2) is a Jinja2 file in which the variables are filled in:

<!doctype html>
<title>{{ site_title }}</title>
<h1>{{ site_title }}</h1>

files/default.conf is your own nginx configuration. The project’s directory structure looks like this:

ansible-web/
├── inventory.ini
├── webserver.yml
├── templates/
│   └── index.html.j2
└── files/
    └── default.conf

A few things worth noticing:

  • The name of each task describes the state we want, not what we are doing. That way the output is readable too.
  • We refer to modules by their full name (FQCN, for example ansible.builtin.apt). The short name would also work, but the full name is unambiguous, and ansible-lint asks for it too.
  • A handler only runs if a task that refers to it with notify actually changed something. If the configuration didn’t change, nginx isn’t reloaded either.

Running it: a dry run first

Before you run it for real, see what it would change:

ansible-playbook -i inventory.ini webserver.yml --check --diff

--check doesn’t change anything, and --diff shows the changes to files. If everything is fine, run it for real:

ansible-playbook -i inventory.ini webserver.yml

At the end, a summary (PLAY RECAP) shows for each machine how many tasks ran, how many made a change (changed), and where there were errors. Run it a second time too: if the playbook is written well, the second time every task will be ok, and none changed. This is idempotence in practice.

Where next?

  • Version control. Put the playbooks and the inventory into Git. That way you can see who changed what and when, and a faulty change can be reverted.
  • Secrets. Don’t write passwords or API keys into the playbook as plain text; that is what ansible-vault is for.
  • Roles. When the playbook grows, split it into roles (for example nginx, php, base), so you can reuse them in other projects.
  • Linting. ansible-lint flags common mistakes and bad practices. It is worth knowing that since version 2.19, ansible-core handles templates and conditionals more strictly; old examples found on the internet may fail because of this.
  • Containers. If you use Docker on the servers, Ansible can also install it; we described the manual steps in the aWh knowledge base, and they translate well into a playbook.

Ansible pays off most when every server change goes through it, and manual changes remain the exception. If you would like to move your existing servers to a repeatable configuration described as code, take a look at our Cloud and DevOps service.

Let’s talk about your project

Tell us briefly how we can help, and we will get back to you as soon as we can.

Get in touch