Add end_batch meta task (#74899)

* Add end_batch meta task

* Add note

* Fix sanity

changelogs/fragments/end_batch-meta-task.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - Add ``end_batch`` meta task.

lib/ansible/modules/meta.py

@@ -33,7 +33,9 @@ options:
         - C(end_play) (added in Ansible 2.2) causes the play to end without failing the host(s). Note that this affects all hosts.
         - C(reset_connection) (added in Ansible 2.3) interrupts a persistent connection (i.e. ssh + control persist)
         - C(end_host) (added in Ansible 2.8) is a per-host variation of C(end_play). Causes the play to end for the current host without failing it.
-    choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection ]
+        - C(end_batch) (added in Ansible 2.12) causes the current batch (see C(serial)) to end without failing the host(s).
+          Note that with C(serial=0) or undefined this behaves the same as C(end_play).
+    choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection, end_batch ]
     required: true
 notes:
     - C(meta) is not really a module nor action_plugin as such it cannot be overwritten.

lib/ansible/plugins/strategy/__init__.py

@@ -1156,6 +1156,15 @@ class StrategyBase:
             else:
                 skipped = True
                 skip_reason += ', not clearing host error state for %s' % target_host.name
+        elif meta_action == 'end_batch':
+            if _evaluate_conditional(target_host):
+                for host in self._inventory.get_hosts(iterator._play.hosts):
+                    if host.name not in self._tqm._unreachable_hosts:
+                        iterator._host_states[host.name].run_state = iterator.ITERATING_COMPLETE
+                msg = "ending batch"
+            else:
+                skipped = True
+                skip_reason += ', continuing current batch'
         elif meta_action == 'end_play':
             if _evaluate_conditional(target_host):
                 for host in self._inventory.get_hosts(iterator._play.hosts):

test/integration/targets/meta_tasks/runme.sh

@@ -56,3 +56,12 @@ for test_strategy in linear free; do
   grep -q "META: ending play" <<< "$out"
   grep -qv 'Failed to end using end_play' <<< "$out"
 done
+
+# test end_batch meta task
+for test_strategy in linear free; do
+  out="$(ansible-playbook test_end_batch.yml -i inventory.yml -e test_strategy=$test_strategy -vv "$@")"
+
+  [ "$(grep -c "Using end_batch" <<< "$out" )" -eq 2 ]
+  [ "$(grep -c "META: ending batch" <<< "$out" )" -eq 2 ]
+  grep -qv 'Failed to end_batch' <<< "$out"
+done

test/integration/targets/meta_tasks/test_end_batch.yml

@@ -0,0 +1,13 @@
+- name: Testing end_batch with strategy {{ test_strategy | default('linear') }}
+  hosts: testhost:testhost2
+  gather_facts: no
+  serial: 1
+  strategy: "{{ test_strategy | default('linear') }}"
+  tasks:
+    - debug:
+        msg: "Using end_batch, current host: {{ inventory_hostname }}, current batch: {{ ansible_play_batch }}"
+
+    - meta: end_batch
+
+    - fail:
+        msg: "Failed to end_batch, current host: {{ inventory_hostname }}, current batch: {{ ansible_play_batch }}"