From 269a6d46d62b04fa59f3c85b507f972b3e20aa48 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Sat, 3 Mar 2012 14:13:31 -0500 Subject: [PATCH] attempt to explain import syntax in ansible-playbook manpage. Can't include examples inline because github won't display them well, want to move this file to markdown soon. --- docs/man/man5/ansible-playbook.5.asciidoc | 40 +++++++++++++++++------ 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/docs/man/man5/ansible-playbook.5.asciidoc b/docs/man/man5/ansible-playbook.5.asciidoc index c4f63bb00b0..2b1bc9bf67b 100644 --- a/docs/man/man5/ansible-playbook.5.asciidoc +++ b/docs/man/man5/ansible-playbook.5.asciidoc @@ -28,24 +28,44 @@ Playbooks are written in YAML. EXAMPLE ------- -see https://github.com/mpdehaan/ansible/blob/master/examples/playbook.yml +see + +https://github.com/mpdehaan/ansible/blob/master/examples/playbook.yml + +https://github.com/mpdehaan/ansible/blob/master/examples/base.yml + +https://github.com/mpdehaan/ansible/blob/master/examples/handlers.yml WHAT THE EXAMPLE MEANS ----------------------- -Here's what the above example will do. +Here's what playbook.yml (above) will do. + +The first pattern will select all hosts. The patterns are the same +as supported by /usr/bin/ansible. + +First, it will run all the modules specified in base.yml. Includes can +be used to implement classes of things, and if you wanted, a playbook +could consist of nothing but include files. This is an example of an +include. + +After processing base.yml, on each host we'll write for +a JSON file into /etc/ansible/setup on each remote system with the +values max_clients and http_port. -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, we'll use a Jinja2 template locally residing at +/srv/templates/httpd.j2 to write the Apache config file on each host, +using the previous values in that setup file. -Next, use a Jinja2 template locally residing at -/srv/templates/httpd.j2 to write the Apache config file on each host -to the path /etc/httpd.conf, using the previous values. +Next, We'll ensure that apache is running if stopped. -We'll ensure that apache is running if stopped. +The template task set up a notifier, which means if the configuration +file actually changed, we have a named handler, in this case, 'restart apache' +to run. In this case, all the notifiers come from handlers.yml, though it's +also ok to express handlers directly in the main yaml file too. Using +the include promotes reuse. -If and only if the config file changed, note that we need to restart +What does the handler say? 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.