From 86ea21a73d0956c0ceac7c81a01d58892f8575a1 Mon Sep 17 00:00:00 2001
From: Brian Coca <bcoca@users.noreply.github.com>
Date: Wed, 28 Sep 2016 10:32:19 -0400
Subject: [PATCH] ansible_play_batch (#17779)
* ansible_play_batch
* added version added
---
CHANGELOG.md | 2 ++
docsite/rst/playbooks_variables.rst | 8 +++++++-
lib/ansible/vars/__init__.py | 1 +
3 files changed, 10 insertions(+), 1 deletion(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2e1f478a6ab..1386d7d73b7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -249,6 +249,7 @@ Ansible Changes By Release
* Only check if the default ssh client supports ControlPersist once instead of once for each host + task combination.
* Fix a problem with the pip module updating the python pip package itself.
* ansible_play_hosts is a new magic variable to provide a list of hosts in scope for the current play. Unlike play_hosts it is not subject to the 'serial' keyword.
+* ansible_play_batch is a new magic variable meant to substitute the current play_hosts.
###For custom front ends using the API:
* ansible.parsing.vault:
@@ -481,6 +482,7 @@ Notice given that the following will be removed in Ansible 2.4:
* Deprecated the use of "bare" variables in loops (ie. `with_items: foo`, where `foo` is a variable).
The full jinja2 variable syntax of `{{foo}}` should always be used instead. This warning will be removed
completely in 2.3, after which time it will be an error.
+* play_hosts magic variable, use ansible_play_batch or ansible_play_hosts instead.
## 2.0.2 "Over the Hills and Far Away"
diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst
index e5c310f2cef..cce72edd5e4 100644
--- a/docsite/rst/playbooks_variables.rst
+++ b/docsite/rst/playbooks_variables.rst
@@ -673,8 +673,14 @@ be useful for when you don't want to rely on the discovered hostname ``ansible_h
reasons. If you have a long FQDN, ``inventory_hostname_short`` also contains the part up to the first
period, without the rest of the domain.
+``play_hosts`` has been deprecated in 2.2, it was the same as the new ``ansible_play_batch`` variable.
+
+.. versionadded:: 2.2
``ansible_play_hosts`` is the full list of all hosts still active in the current play.
-``play_hosts`` is available as a list of hostnames that are in scope for the current 'batch' of the play. The batch size is defined by ``serial``, when not set it is equivalent to the whole play (making it the same as ``ansible_play_hosts``).
+.. versionadded:: 2.2
+``ansible_play_batch`` is available as a list of hostnames that are in scope for the current 'batch' of the play. The batch size is defined by ``serial``, when not set it is equivalent to the whole play (making it the same as ``ansible_play_hosts``).
+
+
These vars may be useful for filling out templates with multiple hostnames or for injecting the list into the rules for a load balancer.
Don't worry about any of this unless you think you need it. You'll know when you do.
diff --git a/lib/ansible/vars/__init__.py b/lib/ansible/vars/__init__.py
index 1765037218f..b50fb22712c 100644
--- a/lib/ansible/vars/__init__.py
+++ b/lib/ansible/vars/__init__.py
@@ -414,6 +414,7 @@ class VariableManager:
# however this would take work in the templating engine, so for now
# we'll add both so we can give users something transitional to use
variables['play_hosts'] = [x.name for x in self._inventory.get_hosts()]
+ variables['ansible_play_batch'] = [x.name for x in self._inventory.get_hosts()]
variables['ansible_play_hosts'] = [x.name for x in self._inventory.get_hosts(pattern=play.hosts or 'all', ignore_restrictions=True)]
# the 'omit' value alows params to be left out if the variable they are based on is undefined