Merge pull request #15114 from djmattyg007/document_squash_actions_config_setting

Add documentation for squash_actions configuration setting

3 files changed, 24 insertions, 1 deletions

diff --git a/docsite/rst/intro_configuration.rst b/docsite/rst/intro_configuration.rst
index 2d12825ea0..b10f460db2 100644
--- a/docsite/rst/intro_configuration.rst
+++ b/docsite/rst/intro_configuration.rst
@@ -628,6 +628,23 @@ Additional paths can be provided separated by colon characters, in the same way
 Roles will be first searched for in the playbook directory.  Should a role not be found, it will indicate all the possible paths
 that were searched.
 
+.. _cfg_squash_actions:
+
+squash_actions
+==============
+
+.. versionadded:: 2.0
+
+Ansible can optimise actions that call modules that support list parameters when using with\_ looping.
+Instead of calling the module once for each item, the module is called once with the full list.
+
+The default value for this setting is only for certain package managers, but it can be used for any module::
+
+    squash_actions = apk,apt,dnf,package,pacman,pkgng,yum,zypper
+
+Currently, this is only supported for modules that have a name parameter, and only when the item is the
+only thing being passed to the parameter.
+
 .. _cfg_strategy_plugins:
 
 strategy_plugins
diff --git a/examples/ansible.cfg b/examples/ansible.cfg
index fe60bc71aa..98657cc062 100644
--- a/examples/ansible.cfg
+++ b/examples/ansible.cfg
@@ -199,6 +199,12 @@
 #retry_files_enabled = False
 #retry_files_save_path = ~/.ansible-retry
 
+# squash actions
+# Ansible can optimise actions that call modules with list parameters
+# when looping. Instead of calling the module once per with_ item, the
+# module is called once with all items at once. Currently this only works
+# under limited circumstances, and only with parameters named 'name'.
+#squash_actions = apk,apt,dnf,package,pacman,pkgng,yum,zypper
 
 # prevents logging of task data, off by default
 #no_log = False
diff --git a/lib/ansible/constants.py b/lib/ansible/constants.py
index 365bda04d0..ea4f909cf5 100644
--- a/lib/ansible/constants.py
+++ b/lib/ansible/constants.py
@@ -203,7 +203,7 @@ DEFAULT_BECOME_ASK_PASS   = get_config(p, 'privilege_escalation', 'become_ask_pa
 # the module takes both, bad things could happen.
 # In the future we should probably generalize this even further
 # (mapping of param: squash field)
-DEFAULT_SQUASH_ACTIONS         = get_config(p, DEFAULTS, 'squash_actions',     'ANSIBLE_SQUASH_ACTIONS', "apt, dnf, package, pkgng, yum, zypper", islist=True)
+DEFAULT_SQUASH_ACTIONS         = get_config(p, DEFAULTS, 'squash_actions',     'ANSIBLE_SQUASH_ACTIONS', "apk, apt, dnf, package, pacman, pkgng, yum, zypper", islist=True)
 # paths
 DEFAULT_ACTION_PLUGIN_PATH     = get_config(p, DEFAULTS, 'action_plugins',     'ANSIBLE_ACTION_PLUGINS', '~/.ansible/plugins/action:/usr/share/ansible/plugins/action', ispath=True)
 DEFAULT_CACHE_PLUGIN_PATH      = get_config(p, DEFAULTS, 'cache_plugins',      'ANSIBLE_CACHE_PLUGINS', '~/.ansible/plugins/cache:/usr/share/ansible/plugins/cache', ispath=True)