From 3422ae6737bf1682131a296ab6361ab0e4bf5a41 Mon Sep 17 00:00:00 2001
From: Michael DeHaan <michael.dehaan@gmail.com>
Date: Sat, 23 Feb 2013 14:56:25 -0500
Subject: [PATCH] Document how to do task includes using with_items and
 externalized data.

---
 docsite/rst/playbooks.rst  |  4 ++-
 docsite/rst/playbooks2.rst | 56 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/docsite/rst/playbooks.rst b/docsite/rst/playbooks.rst
index 0059adbdef..6e0d92476c 100644
--- a/docsite/rst/playbooks.rst
+++ b/docsite/rst/playbooks.rst
@@ -295,7 +295,7 @@ won't need them for much else.
    Notify handlers are always run in the order written.
 
 
-Include Files And Encouraging Reuse
+Task Include Files And Encouraging Reuse
 ```````````````````````````````````
 
 Suppose you want to reuse lists of tasks between plays or playbooks.  You can use
@@ -347,6 +347,8 @@ which also supports structured variables::
               - beta
               - gamma
 
+Playbooks can include other playbooks too, but that's mentioned in a later section.
+
 .. note::
    As of 1.0, task include statements can be used at arbitrary depth.
    They were previously limited to a single level, so task includes
diff --git a/docsite/rst/playbooks2.rst b/docsite/rst/playbooks2.rst
index aceffc26db..756895ef5f 100644
--- a/docsite/rst/playbooks2.rst
+++ b/docsite/rst/playbooks2.rst
@@ -946,6 +946,62 @@ feature produces a large amount of output, it is best used when checking a singl
 
     ansible-playbook foo.yml --check --diff --limit foo.example.com
 
+Advanced Task Includes
+``````````````````````
+
+In above sections we talked about task includes, and how to do loops using with_items.  If we wish
+to externalize data from the playbook rules itself, this is possible by combining some concepts.
+
+This is not something everyone may need to do at first, but it's a clever trick and deserves explanation.
+Here is a top level example playbook that loads variables from an external file and also tasks from an 
+external file.  You will note that we use a list (using with_items) as a parameter on the include
+statement.
+
+    ----
+    # file: playbook-demo.yml
+ 
+    hosts: all
+    vars_files:
+       - config/users.yml
+    tasks:
+      - include: tasks/user.yml user=$item
+        with_items: $users
+
+We've defined our user definitions in an external file.  This allows us to reference that list of users in
+multiple playbooks.  The users list also defines users as a list of hashes, rather than just the usernames.
+We are also loading the SSH public keys for those users from the filesystem, though we could choose to embed
+them in the file instead.  It's up to you::
+
+    ----
+    # file: config/users.yml
+
+    users:
+      - name: alice
+        password: cryptedPasswordHere
+        sshkey: $FILE(/home/alice/id_rsa.pub)
+  
+      - name: bob
+        password: cryptedPasswordHere
+        sshkey: $FILE(/home/bob/id_rsa.pub)
+
+Now that we have these two things together, we can write a task include file the playbook can use that sets
+up *all* of the users, rather than mentioning each user by name, or going to lots of trouble to correlate
+the user names with the SSH keys, and so on::
+
+    ---
+    # file: tasks/user.yml
+
+    - name: ensure user ${user.username} exists
+      action: user state=present name=${user.username} password=${user.password}
+
+    - name: install authorized keys for ${user.username}
+      action: authorized_key state=present user=${user.username} key="${user.sshkey}"
+
+If you can follow this example, you've done pretty well!  It combines most of the language features
+of example all together.  As you can see, there are lots of different ways to load data from
+sources, and to organize things.  Ansible does not really make you pick one or the other, so choose
+an approach that works best for you.
+
 Style Points
 ````````````