What is Ansible

The problem: scripts drift apart

Picture this: you have five servers, and you configure them by hand. On each one you ran the same set of commands, but something is always a little different. Then you hired a colleague, and they set up the sixth one their own way. A year later nobody remembers why web-3 runs a different version of nginx.

A bash script doesn't save you either. It doesn't know the current state of the system. Run it twice and it can break what was already working. Every server picks up manual tweaks that are never written down anywhere.

Ansible solves this differently: you describe the desired state of the system, not a sequence of commands. Ansible figures out what's already like that and what needs fixing.

The agentless push model

The main thing that sets Ansible apart is that it's agentless. You don't install an agent or a daemon on the managed servers. Ansible connects over SSH and does its job.

Two terms for the whole course. Control node is the machine where Ansible is installed and from which you run it (your laptop or a dedicated server). Managed node is a server that Ansible manages.

Here's what that looks like in detail:

1. The control node reads the inventory (the list of hosts).
2. It connects to each managed node over SSH.
3. It copies a small Python module into a temporary directory on the host.
4. It runs the module and collects the result as JSON.
5. It removes the temporary directory.

All of this happens over SSH, and no permanent process is left on the target server. Once Ansible is done, nothing is running on the host that knows about it.

This is a push model: the initiative always sits with the control node. You run a playbook, and the control node itself reaches out to the hosts and applies the changes. The target servers are passive. They don't know about Ansible and don't request anything themselves.

The opposite also exists: the pull model. That's how Puppet and Chef work by default. Every host runs an agent daemon that periodically reaches out to a central server on its own, fetches its configuration and applies it locally. You need an agent on every server plus a central server with certificates, which means a whole separate piece of infrastructure. SaltStack is more flexible: it can do both push and pull.

Pull-based systems still live on in large, old infrastructures. But in newer teams it's more common to start with Ansible: if you can SSH into a server, you can already configure it, nothing needs to be installed on the hosts.

What to install

On the control node:

• Python. The minimum version depends on the ansible-core release: for ansible-core 2.21 that's Python 3.12-3.14. Check current numbers in the support matrix.
• Ansible itself.

First, figure out exactly what you're installing. There are two packages, and they're named similarly.

ansible-core is the engine: the executor, the ansible, ansible-playbook, ansible-vault commands, and a small set of built-in modules (ansible.builtin.*). ansible is a meta-package: the same core plus several hundred community collections (modules for AWS, Docker, PostgreSQL and more). It weighs noticeably more. For learning and everyday work, take the meta-package ansible. ansible-core is for when you want the minimum, with collections installed separately through ansible-galaxy.

The packages have different version numbers: for example, the ansible 14.x meta-package is built on top of ansible-core 2.21.

Now, how to install it. The usual advice pip install ansible fails on recent systems:

error: externally-managed-environment

That's how Debian 12, Ubuntu 23.04 and newer, and Alpine 3.19 and newer behave. The reason is PEP 668: the system Python is marked as managed by the package manager, and pip refuses to write into it, so it doesn't break system utilities. The --break-system-packages flag turns this protection off, but then it installs packages straight into the system Python. That's exactly what the protection is there to prevent.

Working options:

# pipx: installs into an isolated environment, puts the commands on PATH
pipx install --include-deps ansible

# or manually through venv
python3 -m venv ~/.venvs/ansible
~/.venvs/ansible/bin/pip install ansible

You need the --include-deps flag because the ansible meta-package itself doesn't contain any commands, they come from the ansible-core dependency. Without the flag, pipx won't put them on PATH. For ansible-core alone the flag isn't needed: pipx install ansible-core.

Or from your distribution's repository, if the version suits you:

sudo apt install ansible

The distribution's package usually lags behind the latest release, sometimes by several versions. That's fine for learning; for work people more often use pipx, since it's easier to control the version.

On managed nodes:

• An SSH server (almost always already there) and a user you can SSH in as.
• Python. For ansible-core 2.21, the host needs Python 3.9-3.14. It's usually already there, and we'll cover what to do without it in lesson 4.

Windows. The control node doesn't work natively on Windows, you need WSL. Windows can be a managed host. The classic route is WinRM, and since ansible-core 2.18 SSH is officially supported too (it worked experimentally from 2.8, you need OpenSSH 7.9 or newer, meaning Windows Server 2022).

Idempotency: a teaser

If Ansible says "nginx must be installed and running", it first checks: what if it's already installed and running? If so, it does nothing. Run the playbook ten times if you want, the result is the same.

This is called idempotency. We'll cover it in detail in lesson 5.

When Ansible fits, and when it doesn't

Good fit:

• Server configuration: packages, config files, users, services.
• Deploying applications across a fleet of machines.
• Ad-hoc operations: "run uptime on every staging server".
• Creating cloud resources (there are collections for AWS, GCP, Hetzner), though Terraform is more often used for that.

Not its territory:

• Container orchestration. That's Kubernetes.
• A CI/CD pipeline by itself. That's GitLab CI, GitHub Actions.
• Continuous real-time state monitoring. Ansible isn't a daemon: it only works while you have it running.

Common mistakes

• pip install ansible into the system Python. You get externally-managed-environment and work around it with the --break-system-packages flag. Works until the next system update. Install through pipx or venv instead.
• Installing Ansible on managed nodes. No need. Ansible lives only on the control node, hosts only need SSH and Python.
• Mixing up ansible and ansible-core. A module from a collection, for example community.docker.docker_container, is in the ansible meta-package, but not in ansible-core alone, until you install the collection through ansible-galaxy.
• Trying to run Ansible in PowerShell. On Windows the control node only works through WSL.

What you'll need for the tasks

• Understanding how a control node differs from a managed node.
• The externally-managed-environment message and the ways to work around it without breaking the system: venv and pipx.
• The command python3 -m venv <folder>, and that afterward pip runs from <folder>/bin/pip.
• That ansible --version shows the core version on its first line: ansible [core 2.21.5].
• What Ansible does on the host when it runs a module (see the section "The agentless push model").
• The command ansible <host> -m ansible.builtin.ping: it checks that Ansible can reach the host and run a module there. We'll cover ad-hoc commands in detail in the next lesson.

What to remember

Ansible solves the reproducibility problem: you describe the desired state, not a sequence of commands.

Nothing is installed on managed nodes; they only need SSH and Python. The control node itself reaches the hosts over SSH (push), there are no agents and no central server.

ansible-core is the engine, ansible is the same thing plus community collections. You can't install it into the system Python through pip on Debian 12, Ubuntu 23.04+ and Alpine 3.19+ (PEP 668): use pipx, venv or your distribution's package.

In the next lesson we'll cover the inventory and ad-hoc commands.