Docs for module_defaults feature (#39932)

docs/docsite/keyword_desc.yml

@@ -43,6 +43,7 @@ loop_control: |
     .. seealso:: :ref:`loop_control`
 
 max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed.
+module_defaults: Specifies default parameter values for modules.
 name: "Identifier. Can be used for documentation, in or tasks/handlers."
 no_log: Boolean that controls information disclosure.
 notify: "List of handlers to notify when the task returns a 'changed=True' status."

docs/docsite/rst/user_guide/playbooks_module_defaults.rst

@@ -0,0 +1,74 @@
+Module defaults
+===============
+
+If you find yourself calling the same module repeatedly with the same arguments, it can be useful to define default arguments for that particular module using the ``module_defaults`` attribute.
+
+Here is a basic example::
+
+    - hosts: localhost
+      module_defaults:
+        file:
+          owner: root
+          group: root
+          mode: 0755
+      tasks:
+        - file:
+            state: touch
+            path: /tmp/file1
+        - file:
+            state: touch
+            path: /tmp/file2
+        - file:
+            state: touch
+            path: /tmp/file3
+
+The ``module_defaults`` attribute can be used at the play, block, and task level. Any module arguments explicitly specified in a task will override any established default for that module argument::
+
+    - block:
+        - debug:
+            msg: "a different message"
+      module_defaults:
+        debug:
+          msg: "a default message"
+
+It's also possible to remove any previously established defaults for a module by specifying an empty dict::
+
+    - file:
+        state: touch
+        path: /tmp/file1
+      module_defaults:
+        file: {}
+
+.. note::
+    Any module defaults set at the play level (and block/task level when using ``include_role`` or ``import_role``) will apply to any roles used, which may cause unexpected behavior in the role.
+
+Here are some more realistic use cases for this feature.
+
+Interacting with an API that requires auth::
+
+    - hosts: localhost
+      module_defaults:
+        uri:
+          force_basic_auth: true
+          user: some_user
+          password: some_password
+      tasks:
+        - uri:
+            url: http://some.api.host/v1/whatever1
+        - uri:
+            url: http://some.api.host/v1/whatever2
+        - uri:
+            url: http://some.api.host/v1/whatever3
+
+Setting a default AWS region for specific EC2-related modules::
+
+    - hosts: localhost
+      vars:
+        my_region: us-west-2
+      module_defaults:
+        ec2:
+          region: '{{ my_region }}'
+        ec2_instance_facts:
+          region: '{{ my_region }}'
+        ec2_vpc_net_facts:
+          region: '{{ my_region }}'

docs/docsite/rst/user_guide/playbooks_special_topics.rst

@@ -23,3 +23,4 @@ and adopt these only if they seem relevant or useful to your environment.
    playbooks_startnstep
    ../reference_appendices/playbooks_keywords
    playbooks_lookups
+   playbooks_module_defaults