diff --git a/docsite/rst/playbooks.rst b/docsite/rst/playbooks.rst index 0059adbdef5..6e0d92476c1 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 aceffc26db9..756895ef5fc 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 ````````````