Ansible — A Junior DevOps Guide

A mentor-style guide to Ansible for engineers new to configuration management. Read it top-to-bottom, run the examples as you go, break things on purpose.

Who this is for

You know what a Linux shell, SSH, and a YAML file are. You have not written an Ansible playbook yet — or you have, and you want to understand what is actually happening.

What you will be able to do

• Read and explain an existing playbook.
• Write a playbook from a blank file.
• Manage variables, conditionals, loops, handlers, templates.
• Structure a project with roles.
• Handle secrets with ansible-vault.
• Debug when things go wrong (they will).
• Pass a code review of an Ansible change.

Learning path

#	Chapter	What you build
0	Setup	Working ansible + a local test target
1	First contact	ansible ad-hoc, inventory, modules
2	Core concepts	Your first playbook
3	Variables and facts	Reusable playbooks
4	Conditionals and loops	Decision-making
5	Handlers and templates	Reacting to change
6	Roles	Sharing and organizing code
7	Vault and secrets	Not committing passwords
8	Best practices	What senior reviewers expect
9	Debugging	When it doesn't work
10	Real-world project	End-to-end example

Estimated time: 1–2 focused evenings. Chapters with runnable code have a matching folder in examples/ so you can run the same code the guide shows (chapters 1, 8, and 9 are concept chapters — you practice them against earlier examples).

Philosophy (read this once)

Ansible's job is to make a remote machine look the way you described — every time, no surprises, no drift. The word for that is idempotency: running a playbook on a machine that already matches the desired state should change nothing.

If your playbook is not idempotent, you do not have a configuration management tool. You have a remote shell that happens to be yellow.

Repository layout

.
├── README.md                  # this file
├── docs/                      # the guide, one file per chapter
├── examples/                  # runnable playbooks, one dir per hands-on chapter
│   ├── 02-first-playbook/
│   ├── ...
│   └── 10-full-project/
├── inventories/               # sample inventories
├── scripts/                   # self-check tooling + cheatsheet
└── ansible.cfg                # sensible defaults for the examples

Quick start (TL;DR)

# 0. Install
pip install --user ansible-core ansible-lint

# 1. Verify
ansible --version

# 2. Run the self-check
./scripts/self-check.sh

The self-check validates that every example playbook parses, lints clean, and runs in check mode against a local target. If it passes, you are in good shape for the rest of the guide.

Conventions used in this guide

• host$ — a shell on the machine you run Ansible from (the control node).
• target$ — a shell on a machine Ansible configures.
• Code blocks are copy-paste-runnable. If they aren't, the surrounding paragraph says so.
• Anything between ponytail: and the end of a paragraph is a deliberate shortcut your reviewer will accept, and the trade-off you accept by taking it.

When you are stuck

1. Re-read the error. Most Ansible errors say what went wrong.
2. ansible-playbook -vvv playbook.yml — verbosity -vvv shows you exactly what was sent over SSH.
3. --check --diff — predict changes without applying them.
4. If it works once and fails the second time, suspect idempotency.
5. The chapter 09-debugging has more.

Now open 00-setup.md and let's go.