Skip to content
Ansible tutorial
Branch: master
Clone or download
leucos Merge pull request #114 from 7aitsev/small_fixes
Corrected a few imperfections
Latest commit 4a8b7c6 Feb 11, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
step-00 Linter fixes Nov 11, 2018
step-01 Fixed expectations, linter & var files names Nov 11, 2018
step-02 Fixed expectations, linter & var files names Nov 11, 2018
step-03 mixed up ansible-playbook with ansible-pull Feb 10, 2019
step-04 Corrected a paragraph Feb 11, 2019
step-05 Fixed expectations, linter & var files names Nov 11, 2018
step-06 Fixed expectations, linter & var files names Nov 11, 2018
step-07 Fixed condition in a when clause example Feb 11, 2019
step-08 Fixed a typo Feb 11, 2019
step-09 Fixes test expectations Nov 11, 2018
step-10 Fixes test expectations Nov 11, 2018
step-11 Fixes test expectations Nov 11, 2018
step-12 Fixes test expectations Nov 11, 2018
step-13 New step \o/ Nov 11, 2018
test Fixes test expectations Nov 11, 2018
.yamllint Linter fixes Nov 11, 2018 Adds 7aitsev to contributors Feb 10, 2019 fixes Jun 5, 2016
Vagrantfile Fixed expectations, linter & var files names Nov 11, 2018
ansible.cfg Fixes READMEs and deprecations hunting May 4, 2018
package.json adds gitbook functionality Jun 5, 2016

Ansible tutorial

This tutorial presents Ansible step-by-step. You'll need to have a (virtual or physical) machine to act as an Ansible node. A Vagrant environment is provided for going through this tutorial.

Ansible is a configuration management software that lets you control and configure nodes from another machine. What makes it different from other management software is that Ansible uses (potentially existing) SSH infrastructure, while others (Chef, Puppet, ...) need a specific PKI infrastructure to be set up.

Ansible also emphasises push mode, where configuration is pushed from a master machine (a master machine is only a machine where you can SSH to nodes from) to nodes, while most other CM typically do it the other way around (nodes pull their config at times from a master machine).

This mode is really interesting since you do not need to have a 'publicly' accessible 'master' to be able to configure remote nodes: it's the nodes that need to be accessible (we'll see later that 'hidden' nodes can pull their configuration too!), and most of the time they are.

This tutorial has been tested with Ansible 2.7.1.

We're also assuming you have a keypair in your ~/.ssh directory.

Quick start

  • install Vagrant if you don't have it
  • install ansible (preferably 2.7.1 and using pip+virtualenv)
  • vagrant up
  • goto step-00

Complete explanations

Installing Ansible

The reference is the installation guide, but I strongly recomment the Using pip & virtualenv (higly recommended !) method.

Using pip & virtualenv (higly recommended !)

The best way to install Ansible (by far) is to use pip andf virtual environments.

Using virtualenv will let you have multiple Ansible versions installed side by side, and test upgrades or use different versions in different projects. Also, by using a virtualenv, you won't pollute your system's python installation.

Check virtualenvwrapper for this. It makes managing virtualenvs very easy.

Under Ubuntu, installing virtualenv & virtualenvwrapper can be done like so:

sudo apt-get install python-virtualenv virtualenvwrapper python-pip
exec $SHELL

You can then create a virtualenv:

mkvirtualenv ansible-tuto
workon ansible-tuto

(mkvirtualenv usually switches you automatically to your newly created virtualenv, so here workon ansible-tuto is not strictly necessary, but lets be safe).

Then, install ansible via pip:

pip install ansible==2.7.1

(or use whatever version you want).

When you're done, you can deactivate your virtualenv to return to your system's python settings & modules:


If you later want to return to your virtualenv:

workon ansible-tuto

Use lsvirtualenv to list all your virtual environments.

From source (if you want to hack on ansible source code)

Ansible devel branch is always usable, so we'll run straight from a git checkout. You might need to install git for this (sudo apt-get install git on Debian/Ubuntu).

git clone git://
cd ./ansible

At this point, we can load the Ansible environment:

source ./hacking/env-setup

From a distribution package (discouraged)

sudo apt-get install ansible

From a built deb package (discouraged)

When running from an distribution package, this is absolutely not necessary. If you prefer running from an up to date Debian package, Ansible provides a make target to build it. You need a few packages to build the deb and few dependencies:

sudo apt-get install make fakeroot cdbs python-support python-yaml python-jinja2 python-paramiko python-crypto python-pip
git clone git://
cd ./ansible
make deb
sudo dpkg -i ../ansible_x.y_all.deb (version may vary)

Cloning the tutorial

git clone
cd ansible-tuto

Running the tutorials interactively with Docker

You can run the tutorials here interactively including a very simple setup with docker.

Check this repository for details.

Using Vagrant with the tutorial

It's highly recommended to use Vagrant to follow this tutorial. If you don't have it already, setting up should be quite easy and is described in step-00/

If you wish to proceed without Vagrant (not recommended!), go straight to step-01/



  • command or action: ansible module executed in stand-alone mode. Intro in step-02.
  • task: combines an action (a module and its arguments) with a name and optionally some other keywords (like looping directives).
  • play: a yaml structure executing a list of roles or tasks over a list of hosts
  • playbook: yaml file containing multiple plays. Intro in step-04.
  • role: an organisational unit grouping tasks together in order to achieve something (install a piece of software for instance). Intro in step-12.

Just in case you want to skip to a specific step, here is a topic table of contents.


Thanks to all people who have contributed to this tutorial:

(and sorry if I forgot anyone)

I've been using Ansible almost since its birth, but I learned a lot in the process of writing it. If you want to jump in, it's a great way to learn, feel free to add your contributions.

The chapters being written live in the writing branch.

If you have ideas on topics that would require a chapter, please open a PR.

I'm also open on pairing for writing chapters. Drop me a note if you're interested.

If you make changes or add chapters, please fill the test/expectations file and run the tests (test/ See the test/ file for (a bit) more information.

When adding a new chapter (e.g. step-NN), please issue:

cd step-99
ln -sf ../step-NN/{hosts,roles,site.yml,group_vars,host_vars} .

For typos, grammar, etc... please send a PR for the master branch directly.

Thank you!

You can’t perform that action at this time.