diff --git a/docs/docsite/rst/playbooks_async.rst b/docs/docsite/rst/playbooks_async.rst index d9e0fc0407..60fe8c4634 100644 --- a/docs/docsite/rst/playbooks_async.rst +++ b/docs/docsite/rst/playbooks_async.rst @@ -79,6 +79,47 @@ following:: "check on it later" task to fail because the temporary status file that the ``async_status:`` is looking for will not have been written or no longer exist +If you would like to run multiple asynchronous tasks while limiting the amount +of tasks running concurrently, you can do it this way:: + + ##################### + # main.yml + ##################### + - name: Run items asynchronously in batch of two items + vars: + sleep_durations: + - 1 + - 2 + - 3 + - 4 + - 5 + durations: "{{ item }}" + include: execute_batch.yml + with_items: + - "{{ sleep_durations | batch(2) | list }}" + + ##################### + # execute_batch.yml + ##################### + - name: Async sleeping for batched_items + command: sleep {{ async_item }} + async: 45 + poll: 0 + with_items: "{{ durations }}" + loop_control: + loop_var: "async_item" + register: async_results + + - name: Check sync status + async_status: + jid: "{{ async_result_item.ansible_job_id }}" + with_items: "{{ async_results.results }}" + loop_control: + loop_var: "async_result_item" + register: async_poll_results + until: async_poll_results.finished + retries: 30 + .. seealso:: :doc:`playbooks` diff --git a/docs/docsite/rst/playbooks_loops.rst b/docs/docsite/rst/playbooks_loops.rst index e67ab1c307..4dec34bb93 100644 --- a/docs/docsite/rst/playbooks_loops.rst +++ b/docs/docsite/rst/playbooks_loops.rst @@ -59,6 +59,31 @@ Also be aware that when combining `when` with `with_items` (or any other loop st Loops are actually a combination of things `with_` + `lookup()`, so any lookup plugin can be used as a source for a loop, 'items' is lookup. +Please note that ``with_items`` flattens the first depth of the list it is +provided and can yield unexpected results if you pass a list which is composed +of lists. You can work around this by wrapping your nested list inside a list:: + + # This will run debug three times since the list is flattened + - debug: + msg: "{{ item }}" + vars: + nested_list: + - - one + - two + - three + with_items: "{{ nested_list }}" + + # This will run debug once with the three items + - debug: + msg: "{{ item }}" + vars: + nested_list: + - - one + - two + - three + with_items: + - "{{ nested_list }}" + .. _nested_loops: Nested Loops