ansible/docs/man/man5/ansible-playbook.5.asciidoc
Michael DeHaan ba4e36a9a9 Rename 'ensure' to 'state' because I think it's a bit cleaner and doesn't imply
all modules take a common parameter name.  But more or less we still work idempotently
in modules.
2012-02-26 22:31:42 -05:00

116 lines
3 KiB
Text

ansible-modules(5)
=================
:doctype:manpage
:man source: Ansible-playbook
:man version: 0.0.1
:man manual: System administration commands
NAME
----
ansible-playbook - format and function of an ansible playbook file
DESCRIPTION
-----------
Ansible ships with a ansible-playbook tool for running playbooks.
Playbooks can represent frequent tasks, desired system configurations,
or deployment processes.
FORMAT
------
Playbooks are currently writeable in YAML. Other formats (JSON?) may
be supported in the future.
EXAMPLE
-------
FIXME: verify this is correct below
[literal]
---
- 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
WHAT THE EXAMPLE MEANS
-----------------------
Here's what the above example will do.
For all hosts in /etc/ansible/hosts (one host per line) that are named
'webserver-anything', first write a JSON file into /etc/ansible/setup
on each remote system with the values max_clients and http_port.
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.
Ensure that apache is running if stopped.
If and only if the config file changed, note that we need to restart
apache at the end of the run, otherwise, don't bother because we
already know it is running.
HIGH LEVEL EXPLANATION
----------------------
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.
For each pattern, the tasks in the 'tasks' list are executed in order
for all hosts in the host file matching the pattern.
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 'comment:' can be added and will
be ignored.
Most modules accept key=value format arguments.
Handlers are like tasks, but are conditionally executed. If a module
reports a 'change', it can choose to notify a handler by name. If
notified, it will run only for hosts that changed.
FUTURE BEHAVIOR
---------------
What the playbook run does with a host when an error is detected is
currently being refined and is subject to change.
AUTHOR
------
Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.
SEE ALSO
--------
*ansible*(1)
*ansible-playbook*(5) - pending
Ansible home page: <https://github.com/mpdehaan/ansible/>