Skip to content

Commit 789a22b

Browse files
mariolenzfelixfonteins-hertel
authored
Update module default groups documentation (#1893)
* Update module default groups documentation * Apply suggestions from code review Co-authored-by: Felix Fontein <[email protected]> * Fix malformed table * Apply suggestion from s-hertel Co-authored-by: Sloane Hertel <[email protected]> * Fix table (2) * Add reference to runtime.yml --------- Co-authored-by: Felix Fontein <[email protected]> Co-authored-by: Sloane Hertel <[email protected]>
1 parent a662334 commit 789a22b

File tree

1 file changed

+54
-51
lines changed

1 file changed

+54
-51
lines changed

‎docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst

Lines changed: 54 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -102,57 +102,10 @@ Setting a default AWS region for specific EC2-related modules.
102102
Module defaults groups
103103
----------------------
104104

105-
.. versionadded:: 2.7
106-
107-
Ansible 2.7 adds a preview-status feature to group together modules that share common sets of parameters. This makes it easier to author playbooks making heavy use of API-based modules such as cloud modules.
108-
109-
+---------+---------------------------+-----------------+
110-
| Group | Purpose | Ansible Version |
111-
+=========+===========================+=================+
112-
| aws | Amazon Web Services | 2.7 |
113-
+---------+---------------------------+-----------------+
114-
| azure | Azure | 2.7 |
115-
+---------+---------------------------+-----------------+
116-
| gcp | Google Cloud Platform | 2.7 |
117-
+---------+---------------------------+-----------------+
118-
| k8s | Kubernetes | 2.8 |
119-
+---------+---------------------------+-----------------+
120-
| os | OpenStack | 2.8 |
121-
+---------+---------------------------+-----------------+
122-
| acme | ACME | 2.10 |
123-
+---------+---------------------------+-----------------+
124-
| docker* | Docker | 2.10 |
125-
+---------+---------------------------+-----------------+
126-
| ovirt | oVirt | 2.10 |
127-
+---------+---------------------------+-----------------+
128-
| vmware | VMware | 2.10 |
129-
+---------+---------------------------+-----------------+
130-
131-
* The `docker_stack <docker_stack_module>`_ module is not included in the ``docker`` defaults group.
105+
Module default groups allow to provide common parameters to groups of modules that belong together. Collections can define such groups in their ``meta/runtime.yml`` file.
132106

133-
Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - for example ``group/aws``.
134-
135-
In a playbook, you can set module defaults for whole groups of modules, such as setting a common AWS region.
136-
137-
.. code-block:: YAML
138-
139-
# example_play.yml
140-
- hosts: localhost
141-
module_defaults:
142-
group/aws:
143-
region: us-west-2
144-
tasks:
145-
- name: Get info
146-
aws_s3_bucket_info:
147-
148-
# now the region is shared between both info modules
149-
150-
- name: Get info
151-
ec2_ami_info:
152-
filters:
153-
name: 'RHEL*7.5*'
154-
155-
In ansible-core 2.12, collections can define their own groups in the ``meta/runtime.yml`` file. ``module_defaults`` does not take the ``collections`` keyword into account, so the fully qualified group name must be used for new groups in ``module_defaults``.
107+
.. note::
108+
``module_defaults`` does not take the ``collections`` keyword into account, so the fully qualified group name must be used for new groups in ``module_defaults``.
156109

157110
Here is an example ``runtime.yml`` file for the ``ns.coll`` collection.
158111
This file defines an action group named ``ns.coll.my_group`` and places the ``sample_module`` from ``ns.coll`` and ``another_module`` from ``another.collection`` into the group.
@@ -175,4 +128,54 @@ This group can now be used in a playbook like this:
175128
option_name: option_value
176129
tasks:
177130
- ns.coll.sample_module:
178-
- another.collection.another_module:
131+
- another.collection.another_module:
132+
133+
For historical reasons and backwards compatibility, there are some special groups:
134+
135+
+---------+--------------------------------------------------------------------------------------------------------------------+
136+
| Group | Extended module group |
137+
+=========+====================================================================================================================+
138+
| aws | amazon.aws.aws and community.aws.aws |
139+
+---------+--------------------------------------------------------------------------------------------------------------------+
140+
| azure | azure.azcollection.azure |
141+
+---------+--------------------------------------------------------------------------------------------------------------------+
142+
| gcp | google.cloud.gcp |
143+
+---------+--------------------------------------------------------------------------------------------------------------------+
144+
| k8s | community.kubernetes.k8s, community.general.k8s, community.kubevirt.k8s, community.okd.k8s, and kubernetes.core.k8s|
145+
+---------+--------------------------------------------------------------------------------------------------------------------+
146+
| os | openstack.cloud.os |
147+
+---------+--------------------------------------------------------------------------------------------------------------------+
148+
| acme | community.crypto.acme |
149+
+---------+--------------------------------------------------------------------------------------------------------------------+
150+
| docker* | community.general.docker and community.docker.docker |
151+
+---------+--------------------------------------------------------------------------------------------------------------------+
152+
| ovirt | ovirt.ovirt.ovirt and community.general.ovirt |
153+
+---------+--------------------------------------------------------------------------------------------------------------------+
154+
| vmware | community.vmware.vmware |
155+
+---------+--------------------------------------------------------------------------------------------------------------------+
156+
157+
* Check out the documentation for the collection or its meta/runtime.yml to see which action plugins and modules are included in the group.
158+
159+
Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - for example ``group/aws``.
160+
161+
In a playbook, you can set module defaults for whole groups of modules, such as setting a common AWS region.
162+
163+
.. code-block:: YAML
164+
165+
# example_play.yml
166+
- hosts: localhost
167+
module_defaults:
168+
group/aws:
169+
region: us-west-2
170+
tasks:
171+
- name: Get info
172+
aws_s3_bucket_info:
173+
174+
# now the region is shared between both info modules
175+
176+
- name: Get info
177+
ec2_ami_info:
178+
filters:
179+
name: 'RHEL*7.5*'
180+
181+
More information on meta/runtime.yml, including the complete format for `action_groups`, can be found in :ref:`meta_runtime_yml`.

0 commit comments

Comments
 (0)