From 318f369969ba92348960f6d7e67a17dc4fbdaf22 Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Wed, 5 Jul 2017 00:20:46 +0200 Subject: [PATCH] filetree: Add documentation for lookup plugin (#26157) * filetree: Add documentation for lookup plugin This is the missing documentation for the filetree lookup plugin. * Fix typo * Edits for grammar and clarity --- docs/docsite/rst/playbooks_loops.rst | 75 +++++++++++++++++++++++++--- 1 file changed, 69 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/playbooks_loops.rst b/docs/docsite/rst/playbooks_loops.rst index 8e3e3ebc4c..e67ab1c307 100644 --- a/docs/docsite/rst/playbooks_loops.rst +++ b/docs/docsite/rst/playbooks_loops.rst @@ -176,18 +176,81 @@ Looping over Fileglobs .. note:: When using a relative path with ``with_fileglob`` in a role, Ansible resolves the path relative to the `roles//files` directory. + +Looping over Filetrees +`````````````````````` + +``with_filetree`` recursively matches all files in a directory tree, enabling you to template a complete tree of files on a target system while retaining permissions and ownership. + +The ``filetree`` lookup-plugin supports directories, files and symlinks, including SELinux and other file properties. Here is a complete list of what each file object consists of: + +* src +* root +* path +* mode +* state +* owner +* group +* seuser +* serole +* setype +* selevel +* uid +* gid +* size +* mtime +* ctime + +If you provide more than one path, it will implement a ``with_first_found`` logic, and will not process entries it already processed in previous paths. This enables the user to merge different trees in order of importance, or add role_vars specific paths to influence different instances of the same role. + +Here is an example of how we use with_filetree within a role. The ``web/`` path is relative to either ``roles//files/`` or ``files/``:: + + --- + - name: Create directories + file: + path: /web/{{ item.path }} + state: directory + mode: '{{ item.mode }}' + with_filetree: web/ + when: item.state == 'directory' + + - name: Template files + template: + src: '{{ item.src }}' + dest: /web/{{ item.path }} + mode: '{{ item.mode }}' + with_filetree: web/ + when: item.state == 'file' + + - name: Recreate symlinks + file: + src: '{{ item.src }}' + dest: /web/{{ item.path }} + state: link + force: yes + mode: '{{ item.mode }}' + with_filetree: web/ + when: item.state == 'link' + + +The following properties are also available: + +* ``root``: allows filtering by original location +* ``path``: contains the relative path to root +* ``uidi``, ``gid``: force-create by exact id, rather than by name +* ``size``, ``mtime``, ``ctime``: filter out files by size, mtime or ctime + + Looping over Parallel Sets of Data `````````````````````````````````` -.. note:: This is an uncommon thing to want to do, but we're documenting it for completeness. You probably won't be reaching for this one often. - -Suppose you have the following variable data was loaded in via somewhere:: +Suppose you have the following variable data:: --- alpha: [ 'a', 'b', 'c', 'd' ] numbers: [ 1, 2, 3, 4 ] -And you want the set of '(a, 1)' and '(b, 2)' and so on. Use 'with_together' to get this:: +...and you want the set of '(a, 1)' and '(b, 2)'. Use 'with_together' to get this:: tasks: - debug: @@ -202,7 +265,7 @@ Looping over Subelements Suppose you want to do something like loop over a list of users, creating them, and allowing them to login by a certain set of SSH keys. -How might that be accomplished? Let's assume you had the following defined and loaded in via "vars_files" or maybe a "group_vars/all" file:: +In this example, we'll assume you have the following defined and loaded in via "vars_files" or maybe a "group_vars/all" file:: --- users: @@ -231,7 +294,7 @@ How might that be accomplished? Let's assume you had the following defined and - "*.*:SELECT" - "DB2.*:ALL" -It might happen like so:: +You could loop over these subelements like this:: - name: Create User user: