From 6104406eaf39201c1c8daaa5078df41f2aac422c Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 29 Oct 2024 14:23:25 -0400 Subject: [PATCH] Update module default groups documentation (#1893) (#2074) * Update module default groups documentation * Apply suggestions from code review Co-authored-by: Felix Fontein * Fix malformed table * Apply suggestion from s-hertel Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> * Fix table (2) * Add reference to runtime.yml --------- Co-authored-by: Felix Fontein Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> (cherry picked from commit 789a22b638aeee3f0529a43f0c477174fc48f021) Co-authored-by: Mario Lenz --- .../playbooks_module_defaults.rst | 105 +++++++++--------- 1 file changed, 54 insertions(+), 51 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst b/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst index abfe61574d0..d5c78f4570d 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst @@ -102,57 +102,10 @@ Setting a default AWS region for specific EC2-related modules. Module defaults groups ---------------------- -.. versionadded:: 2.7 - -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. - -+---------+---------------------------+-----------------+ -| Group | Purpose | Ansible Version | -+=========+===========================+=================+ -| aws | Amazon Web Services | 2.7 | -+---------+---------------------------+-----------------+ -| azure | Azure | 2.7 | -+---------+---------------------------+-----------------+ -| gcp | Google Cloud Platform | 2.7 | -+---------+---------------------------+-----------------+ -| k8s | Kubernetes | 2.8 | -+---------+---------------------------+-----------------+ -| os | OpenStack | 2.8 | -+---------+---------------------------+-----------------+ -| acme | ACME | 2.10 | -+---------+---------------------------+-----------------+ -| docker* | Docker | 2.10 | -+---------+---------------------------+-----------------+ -| ovirt | oVirt | 2.10 | -+---------+---------------------------+-----------------+ -| vmware | VMware | 2.10 | -+---------+---------------------------+-----------------+ - -* The `docker_stack `_ module is not included in the ``docker`` defaults group. +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. -Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - for example ``group/aws``. - -In a playbook, you can set module defaults for whole groups of modules, such as setting a common AWS region. - -.. code-block:: YAML - - # example_play.yml - - hosts: localhost - module_defaults: - group/aws: - region: us-west-2 - tasks: - - name: Get info - aws_s3_bucket_info: - - # now the region is shared between both info modules - - - name: Get info - ec2_ami_info: - filters: - name: 'RHEL*7.5*' - -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``. +.. note:: + ``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``. Here is an example ``runtime.yml`` file for the ``ns.coll`` collection. 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: option_name: option_value tasks: - ns.coll.sample_module: - - another.collection.another_module: \ No newline at end of file + - another.collection.another_module: + +For historical reasons and backwards compatibility, there are some special groups: + ++---------+--------------------------------------------------------------------------------------------------------------------+ +| Group | Extended module group | ++=========+====================================================================================================================+ +| aws | amazon.aws.aws and community.aws.aws | ++---------+--------------------------------------------------------------------------------------------------------------------+ +| azure | azure.azcollection.azure | ++---------+--------------------------------------------------------------------------------------------------------------------+ +| gcp | google.cloud.gcp | ++---------+--------------------------------------------------------------------------------------------------------------------+ +| k8s | community.kubernetes.k8s, community.general.k8s, community.kubevirt.k8s, community.okd.k8s, and kubernetes.core.k8s| ++---------+--------------------------------------------------------------------------------------------------------------------+ +| os | openstack.cloud.os | ++---------+--------------------------------------------------------------------------------------------------------------------+ +| acme | community.crypto.acme | ++---------+--------------------------------------------------------------------------------------------------------------------+ +| docker* | community.general.docker and community.docker.docker | ++---------+--------------------------------------------------------------------------------------------------------------------+ +| ovirt | ovirt.ovirt.ovirt and community.general.ovirt | ++---------+--------------------------------------------------------------------------------------------------------------------+ +| vmware | community.vmware.vmware | ++---------+--------------------------------------------------------------------------------------------------------------------+ + +* Check out the documentation for the collection or its meta/runtime.yml to see which action plugins and modules are included in the group. + +Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - for example ``group/aws``. + +In a playbook, you can set module defaults for whole groups of modules, such as setting a common AWS region. + +.. code-block:: YAML + + # example_play.yml + - hosts: localhost + module_defaults: + group/aws: + region: us-west-2 + tasks: + - name: Get info + aws_s3_bucket_info: + + # now the region is shared between both info modules + + - name: Get info + ec2_ami_info: + filters: + name: 'RHEL*7.5*' + +More information on meta/runtime.yml, including the complete format for `action_groups`, can be found in :ref:`meta_runtime_yml`.