ansible/docs/man/man5/ansible-playbook.5

'\" t
.\"     Title: ansible-modules
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 02/26/2012
.\"    Manual: System administration commands
.\"    Source: Ansible-playbook 0.0.1
.\"  Language: English
.\"
.TH "ANSIBLE\-MODULES" "5" "02/26/2012" "Ansible\-playbook 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible-playbook \- format and function of an ansible playbook file
.SH "DESCRIPTION"
.sp
Ansible ships with a ansible\-playbook tool for running playbooks\&. Playbooks can represent frequent tasks, desired system configurations, or deployment processes\&.
.SH "FORMAT"
.sp
Playbooks are currently writeable in YAML\&. Other formats (JSON?) may be supported in the future\&.
.SH "EXAMPLE"
.sp
FIXME: verify this is correct below
.sp
.if n \{\
.RS 4
.\}
.nf
\-\-\-
\- pattern: \'*\'
  hosts: \'/etc/ansible/hosts\'
  tasks:
  \- name:configure template & module variables for future template calls
    action: setup http_port=80 max_clients=200
  \- name: write the apache config file
    action: template src=/srv/mytemplates/httpd\&.j2 dest=/etc/httpd/conf
    notify:
    \- restart apache
  \- name: ensure apache is running
    action: service name=httpd ensure=started
  handlers:
    \- name: restart apache
    \- action: service name=httpd ensure=restarted
.fi
.if n \{\
.RE
.\}
.SH "WHAT THE EXAMPLE MEANS"
.sp
Here\(cqs what the above example will do\&.
.sp
For all hosts in /etc/ansible/hosts (one host per line) that are named \fIwebserver\-anything\fR, first write a JSON file into /etc/ansible/setup on each remote system with the values max_clients and http_port\&.
.sp
Next, use a Jinja2 template locally residing at /srv/mytemplates/httpd\&.j2 to write the Apache config file on each host to the path /etc/httpd/conf, using the previous values\&.
.sp
Ensure that apache is running if stopped\&.
.sp
If and only if the config file changed, note that we need to restart apache at the end of the run, otherwise, don\(cqt bother because we already know it is running\&.
.SH "HIGH LEVEL EXPLANATION"
.sp
Playbooks are executed top down and can contain multiple references to patterns\&. For instance, a playbook could do something to all webservers, then do something to all database servers, then do something different to all webservers again\&.
.sp
For each pattern, the tasks in the \fItasks\fR list are executed in order for all hosts in the host file matching the pattern\&.
.sp
For each task, a name/action pair describes what the task is and what ansible module to use to accomplish the task, along with any arguments\&. Additional fields like \fIcomment:\fR can be added and will be ignored\&.
.sp
Most modules accept key=value format arguments\&.
.sp
Handlers are like tasks, but are conditionally executed\&. If a module reports a \fIchange\fR, it can choose to notify a handler by name\&. If notified, it will run only for hosts that changed\&.
.SH "FUTURE BEHAVIOR"
.sp
What the playbook run does with a host when an error is detected is currently being refined and is subject to change\&.
.SH "AUTHOR"
.sp
Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
.SH "SEE ALSO"
.sp
\fBansible\fR(1)
.sp
\fBansible\-playbook\fR(5) \- pending
.sp
Ansible home page: https://github\&.com/mpdehaan/ansible/