Ansible Documentation

214070

Ansible Documentation

Release 1.5

Ansible

March 01, 2014

CONTENTS

1 About Ansible1

1.1 Introduction

1

1.2 Quickstart Video

30

1.3 Playbooks

30

1.4 Playbooks: Special Topics

77

1.5 About Modules

93

1.6 Module Index

94

1.7 Detailed Guides

401

1.8 Developer Information

422

1.9 Ansible Tower

435

1.10 Community Information

435

1.11 Ansible Galaxy

436

1.12 Frequently Asked Questions

436

1.13 Glossary

440

1.14 YAML Syntax

449

1.15 Ansible Guru

450 i
ii

CHAPTER

ONEABOUT ANSIBLE

Welcome to the Ansible documentation!

Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks

such as continuous deployments or zero downtime rolling updates.

Ansible"s goals are foremost those of simplicity and maximum ease of use. It also has a strong focus on security

and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket

mode and pull modes as alternatives), and a language that is designed around auditability by humans - even those not

familiar with the program.

We believe simplicity is relevant to all sizes of environments and design for busy users of all types - whether this

means developers, sysadmins, release engineers, IT managers, and everywhere in between. Ansible is appropriate for

managing small setups with a handful of instances as well as enterprise environments with many thousands.

Ansible manages machines in an agentless manner. There is never a question of how to upgrade remote daemons or the

problem of not being able to manage systems because daemons are uninstalled. As OpenSSH is one of the most peer

reviewed open source components, the security exposure of using the tool is greatly reduced. Ansible is decentralized

- it relies on your existing OS credentials to control access to remote machines; if needed it can easily connect with

Kerberos, LDAP, and other centralized authentication management systems.

This documentation covers the current released version of Ansible (1.4.5) and also some development version features

(1.5). For recent features, in each section, the version of Ansible where the feature is added is indicated. Ansible,

Inc releases a new major release of Ansible approximately every 2 months. The core application evolves somewhat

conservatively, valuing simplicity in language design and setup, while the community around new modules and plugins

being developed and contributed moves very very quickly, typically adding 20 or so new modules in each release.

1.1

Intr oduction

Before we dive into the really fun parts - playbooks, configuration management, deployment, and orchestration, we"ll

learn how to get Ansible installed and some basic concepts. We"ll go over how to execute ad-hoc commands in parallel

across your nodes using /usr/bin/ansible. We"ll also see what sort of modules are available in Ansible"s core (though

you can also write your own, which we"ll also show later). 1.1.1

Installation 1

Ansible Documentation, Release 1.5

Topics

Installation

-Getting Ansible -Basics / What Will Be Installed -What Version To Pick? -Control Machine Requirements -Managed Node Requirements -Installing the Control Machine

Running From Source

Latest Release Via Yum

Latest Releases Via Apt (Ubuntu)

Latest Releases Via pkg (FreeBSD)

Latest Releases Via Pip

Tarballs of Tagged ReleasesGetting Ansible

You may also wish to follow the

Github project

if you ha vea github account. This is also where we k eepthe issue tracker for sharing bugs and feature ideas.

Basics / What Will Be Installed

Ansible by default manages machines over the SSH protocol.

Once Ansible is installed, it will not add a database, and there will be no daemons to start or keep running. You only

need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines

from that central point. When Ansible manages remote machines, it does not leave software installed or running on

them, so there"s no real question about how to upgrade Ansible when moving to a new version.

What Version To Pick?

Because it runs so easily from source and does not require any installation of software on remote machines, many

users will actually track the development version.

Ansible"s release cycles are usually about two months long. Due to this short release cycle, minor bugs will generally

be fixed in the next release versus maintaining backports on the stable branch. Major bugs will still have maintenance

releases when needed, though these are infrequent.

If you are wishing to run the latest released version of Ansible and you are running Red Hat Enterprise Linux (TM),

CentOS, Fedora, Debian, or Ubuntu, we recommend using the OS package manager.

For other installation options, we recommend installing via "pip", which is the Python package manager, though other

options are also available.

If you wish to track the development release to use and test the latest features, we will share information about running

from source. It"s not necessary to install the program to run from source.

Control Machine Requirements

Currently Ansible can be run from any machine with Python 2.6 installed (Windows isn"t supported for the control

machine). This includes Red Hat, Debian, CentOS, OS X, any of the BSDs, and so on.2Chapter 1. About Ansible

Ansible Documentation, Release 1.5

Managed Node Requirements

On the managed nodes, you only need Python 2.4 or later, but if you are running less than Python 2.5 on the remotes,

you will also need:

•python-simplejsonNote:Ansible"s "raw" module (for executing commands in a quick and dirty way) and the script module don"t evenneed that. So technically, you can use Ansible to install python-simplejson using the raw module, which then allows

you to use everything else. (That"s jumping ahead though.)Note:If you have SELinux enabled on remote nodes, you will also want to install libselinux-python on them beforeusing any copy/file/template related functions in Ansible. You can of course still use the yum module in Ansible to

install this package on remote systems that do not have it.Note:Python 3 is a slightly different language than Python 2 and most Python programs (including Ansible) are notswitching over yet. However, some Linux distributions (Gentoo, Arch) may not have a Python 2.X interpreter installed

by default. On those systems, you should install one, and set the 'ansible_python_interpreter" variable in inventory

(seeInventory) to point at your 2.X Python. Distributions like Red Hat Enterprise Linux, CentOS, Fedora, and Ubuntu

all have a 2.X interpreter installed by default and this does not apply to those distributions. This is also true of nearly

all Unix systems. If you need to bootstrap these remote systems by installing Python 2.X, using the 'raw" module will

be able to do it remotely.Installing the Control Machine

Running From Source

Ansible is trivially easy to run from a checkout, root permissions are not required to use it and there is no software

to actually install for Ansible itself. No daemons or database setup are required. Because of this, many users in our

community use the development version of Ansible all of the time, so they can take advantage of new features when

they are implemented, and also easily contribute to the project. Because there is nothing to install, following the

development version is significantly easier than most open source projects. To install from source.$git clone git://github.com/ansible/ansible.git cd ./ansible source ./hacking/env-setup If you don"t have pip installed in your version of Python, install pip: $ sudo easy_install pip Ansible also uses the following Python modules that need to be installed: $ sudo pip install paramiko PyYAML jinja2 httplib2

Once running the env-setup script you"ll be running from checkout and the default inventory file will be

/etc/ansible/hosts. You can optionally specify an inventory file (seeInventory) other than /etc/ansible/hosts:$echo "127.0.0.1" > ~/ansible_hosts

export

Ansible Documentation

Release 1.5

Ansible

March 01, 2014

CONTENTS

1 About Ansible1

1.1 Introduction

1

1.2 Quickstart Video

30

1.3 Playbooks

30

1.4 Playbooks: Special Topics

77

1.5 About Modules

93

1.6 Module Index

94

1.7 Detailed Guides

401

1.8 Developer Information

422

1.9 Ansible Tower

435

1.10 Community Information

435

1.11 Ansible Galaxy

436

1.12 Frequently Asked Questions

436

1.13 Glossary

440

1.14 YAML Syntax

449

1.15 Ansible Guru

450 i
ii

CHAPTER

ONEABOUT ANSIBLE

Welcome to the Ansible documentation!

Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks

such as continuous deployments or zero downtime rolling updates.

Ansible"s goals are foremost those of simplicity and maximum ease of use. It also has a strong focus on security

and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket

mode and pull modes as alternatives), and a language that is designed around auditability by humans - even those not

familiar with the program.

We believe simplicity is relevant to all sizes of environments and design for busy users of all types - whether this

means developers, sysadmins, release engineers, IT managers, and everywhere in between. Ansible is appropriate for

managing small setups with a handful of instances as well as enterprise environments with many thousands.

Ansible manages machines in an agentless manner. There is never a question of how to upgrade remote daemons or the

problem of not being able to manage systems because daemons are uninstalled. As OpenSSH is one of the most peer

reviewed open source components, the security exposure of using the tool is greatly reduced. Ansible is decentralized

- it relies on your existing OS credentials to control access to remote machines; if needed it can easily connect with

Kerberos, LDAP, and other centralized authentication management systems.

This documentation covers the current released version of Ansible (1.4.5) and also some development version features

(1.5). For recent features, in each section, the version of Ansible where the feature is added is indicated. Ansible,

Inc releases a new major release of Ansible approximately every 2 months. The core application evolves somewhat

conservatively, valuing simplicity in language design and setup, while the community around new modules and plugins

being developed and contributed moves very very quickly, typically adding 20 or so new modules in each release.

1.1

Intr oduction

Before we dive into the really fun parts - playbooks, configuration management, deployment, and orchestration, we"ll

learn how to get Ansible installed and some basic concepts. We"ll go over how to execute ad-hoc commands in parallel

across your nodes using /usr/bin/ansible. We"ll also see what sort of modules are available in Ansible"s core (though

you can also write your own, which we"ll also show later). 1.1.1

Installation 1

Ansible Documentation, Release 1.5

Topics

Installation

-Getting Ansible -Basics / What Will Be Installed -What Version To Pick? -Control Machine Requirements -Managed Node Requirements -Installing the Control Machine

Running From Source

Latest Release Via Yum

Latest Releases Via Apt (Ubuntu)

Latest Releases Via pkg (FreeBSD)

Latest Releases Via Pip

Tarballs of Tagged ReleasesGetting Ansible

You may also wish to follow the

Github project

if you ha vea github account. This is also where we k eepthe issue tracker for sharing bugs and feature ideas.

Basics / What Will Be Installed

Ansible by default manages machines over the SSH protocol.

Once Ansible is installed, it will not add a database, and there will be no daemons to start or keep running. You only

need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines

from that central point. When Ansible manages remote machines, it does not leave software installed or running on

them, so there"s no real question about how to upgrade Ansible when moving to a new version.

What Version To Pick?

Because it runs so easily from source and does not require any installation of software on remote machines, many

users will actually track the development version.

Ansible"s release cycles are usually about two months long. Due to this short release cycle, minor bugs will generally

be fixed in the next release versus maintaining backports on the stable branch. Major bugs will still have maintenance

releases when needed, though these are infrequent.

If you are wishing to run the latest released version of Ansible and you are running Red Hat Enterprise Linux (TM),

CentOS, Fedora, Debian, or Ubuntu, we recommend using the OS package manager.

For other installation options, we recommend installing via "pip", which is the Python package manager, though other

options are also available.

If you wish to track the development release to use and test the latest features, we will share information about running

from source. It"s not necessary to install the program to run from source.

Control Machine Requirements

Currently Ansible can be run from any machine with Python 2.6 installed (Windows isn"t supported for the control

machine). This includes Red Hat, Debian, CentOS, OS X, any of the BSDs, and so on.2Chapter 1. About Ansible

Ansible Documentation, Release 1.5

Managed Node Requirements

On the managed nodes, you only need Python 2.4 or later, but if you are running less than Python 2.5 on the remotes,

you will also need:

•python-simplejsonNote:Ansible"s "raw" module (for executing commands in a quick and dirty way) and the script module don"t evenneed that. So technically, you can use Ansible to install python-simplejson using the raw module, which then allows

you to use everything else. (That"s jumping ahead though.)Note:If you have SELinux enabled on remote nodes, you will also want to install libselinux-python on them beforeusing any copy/file/template related functions in Ansible. You can of course still use the yum module in Ansible to

install this package on remote systems that do not have it.Note:Python 3 is a slightly different language than Python 2 and most Python programs (including Ansible) are notswitching over yet. However, some Linux distributions (Gentoo, Arch) may not have a Python 2.X interpreter installed

by default. On those systems, you should install one, and set the 'ansible_python_interpreter" variable in inventory

(seeInventory) to point at your 2.X Python. Distributions like Red Hat Enterprise Linux, CentOS, Fedora, and Ubuntu

all have a 2.X interpreter installed by default and this does not apply to those distributions. This is also true of nearly

all Unix systems. If you need to bootstrap these remote systems by installing Python 2.X, using the 'raw" module will

be able to do it remotely.Installing the Control Machine

Running From Source

Ansible is trivially easy to run from a checkout, root permissions are not required to use it and there is no software

to actually install for Ansible itself. No daemons or database setup are required. Because of this, many users in our

community use the development version of Ansible all of the time, so they can take advantage of new features when

they are implemented, and also easily contribute to the project. Because there is nothing to install, following the

development version is significantly easier than most open source projects. To install from source.$git clone git://github.com/ansible/ansible.git cd ./ansible source ./hacking/env-setup If you don"t have pip installed in your version of Python, install pip: $ sudo easy_install pip Ansible also uses the following Python modules that need to be installed: $ sudo pip install paramiko PyYAML jinja2 httplib2

Once running the env-setup script you"ll be running from checkout and the default inventory file will be

/etc/ansible/hosts. You can optionally specify an inventory file (seeInventory) other than /etc/ansible/hosts:$echo "127.0.0.1" > ~/ansible_hosts

export