Tagging - switch simplest cases to use doc fragment (#845)

Tagging - switch simplest cases to use doc fragment

Depends-On: #844
SUMMARY
Switch the simplest tagging cases over to using the docs fragment
ISSUE TYPE

Docs Pull Request
Feature Pull Request

COMPONENT NAME
plugins/modules/aws_s3.py
plugins/modules/ec2_eni.py
plugins/modules/ec2_group.py
plugins/modules/ec2_vpc_dhcp_option.py
plugins/modules/ec2_vpc_igw.py
plugins/modules/ec2_vpc_nat_gateway.py
plugins/modules/ec2_vpc_subnet.py
plugins/modules/elb_classic_lb.py
plugins/modules/s3_bucket.py
ADDITIONAL INFORMATION

Reviewed-by: Alina Buzachis <None>

changelogs/fragments/845-tagging.yml

@@ -0,0 +1,6 @@
+minor_changes:
+- aws_s3 - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/amazon.aws/pull/845).
+- ec2_eni - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/amazon.aws/pull/845).
+- ec2_key - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/amazon.aws/pull/845).
+- elb_classic_lb - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/amazon.aws/pull/845).
+- s3_bucket - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/amazon.aws/pull/845).

plugins/modules/aws_s3.py

@@ -166,18 +166,6 @@
     description:
       - KMS key id to use when encrypting objects using I(encrypting=aws:kms). Ignored if I(encryption) is not C(aws:kms).
     type: str
-  tags:
-    description:
-      - Tags dict to apply to the S3 object.
-    type: dict
-    version_added: 2.0.0
-  purge_tags:
-    description:
-      - Whether or not to remove tags assigned to the S3 object if not specified in the playbook.
-      - To remove all tags set I(tags) to an empty dictionary in conjunction with this.
-    type: bool
-    default: True
-    version_added: 2.0.0
   copy_src:
     description:
     - The source details of the object to copy.
@@ -211,10 +199,12 @@
     - "Lester Wade (@lwade)"
     - "Sloane Hertel (@s-hertel)"
     - "Alina Buzachis (@linabuzachis)"
+notes:
+- Support for I(tags) and I(purge_tags) was added in release 2.0.0.
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
-
+- amazon.aws.tags
 '''
 
 EXAMPLES = '''
@@ -935,7 +925,7 @@ def main():
         content_base64=dict(),
         ignore_nonexistent_bucket=dict(default=False, type='bool'),
         encryption_kms_key_id=dict(),
-        tags=dict(type='dict'),
+        tags=dict(type='dict', aliases=['resource_tags']),
         purge_tags=dict(type='bool', default=True),
         copy_src=dict(type='dict', options=dict(bucket=dict(required=True), object=dict(required=True), version_id=dict())),
         validate_bucket_name=dict(type='bool', default=True),

plugins/modules/ec2_eni.py

@@ -108,37 +108,21 @@
     type: bool
   name:
     description:
-      - Name for the ENI. This will create a tag called "Name" with the value assigned here.
+      - Name for the ENI. This will create a tag with the key C(Name) and the value assigned here.
       - This can be used in conjunction with I(subnet_id) as another means of identifiying a network interface.
-      - AWS does not enforce unique Name tags, so duplicate names are possible if you configure it that way.
+      - AWS does not enforce unique C(Name) tags, so duplicate names are possible if you configure it that way.
         If that is the case, you will need to provide other identifying information such as I(private_ip_address) or I(eni_id).
     required: false
     type: str
-  tags:
-    description:
-      - A hash/dictionary of tags to add to the new ENI or to add/remove from an existing one. Please note that
-        the name field sets the "Name" tag.
-      - To clear all tags, set this option to an empty dictionary to use in conjunction with I(purge_tags).
-        If you provide I(name), that tag will not be removed.
-      - To prevent removing any tags set I(purge_tags) to false.
-    type: dict
-    required: false
-    version_added: 1.3.0
-  purge_tags:
-    description:
-      - Indicates whether to remove tags not specified in I(tags) or I(name). This means you have to specify all
-        the desired tags on each task affecting a network interface.
-      - If I(tags) is omitted or None this option is disregarded.
-    default: true
-    type: bool
-    version_added: 1.3.0
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags
 
 notes:
     - This module identifies and ENI based on either the I(eni_id), a combination of I(private_ip_address) and I(subnet_id),
       or a combination of I(instance_id) and I(device_id). Any of these options will let you specify a particular ENI.
+    - Support for I(tags) and I(purge_tags) was added in release 1.3.0.
 '''
 
 EXAMPLES = '''
@@ -853,8 +837,8 @@ def main():
         allow_reassignment=dict(default=False, type='bool'),
         attached=dict(default=None, type='bool'),
         name=dict(default=None, type='str'),
-        tags=dict(type='dict'),
-        purge_tags=dict(default=True, type='bool')
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(default=True, type='bool'),
     )
 
     module = AnsibleAWSModule(

plugins/modules/ec2_group.py

@@ -234,23 +234,11 @@
     default: 'true'
     aliases: []
     type: bool
-  tags:
-    description:
-      - A dictionary of one or more tags to assign to the security group.
-    required: false
-    type: dict
-    aliases: ['resource_tags']
-  purge_tags:
-    description:
-      - If yes, existing tags will be purged from the resource to match exactly what is defined by I(tags) parameter.
-      - If the I(tags) parameter is not set then tags are not modified.
-    required: false
-    default: yes
-    type: bool
 
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags
 
 
 notes:

plugins/modules/ec2_vpc_dhcp_option.py

@@ -78,15 +78,9 @@
   tags:
     description:
       - Tags to be applied to a VPC options set if a new one is created, or
-        if the resource_id is provided. (options must match)
+        if I(dhcp_options_id) is provided. (options must match)
     aliases: [ 'resource_tags']
     type: dict
-  purge_tags:
-    description:
-      - Remove tags not listed in I(tags).
-    type: bool
-    default: true
-    version_added: 2.0.0
   dhcp_options_id:
     description:
       - The resource_id of an existing DHCP options set.
@@ -101,9 +95,12 @@
     default: present
     choices: [ 'absent', 'present' ]
     type: str
+notes:
+- Support for I(purge_tags) was added in release 2.0.0.
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags
 '''
 
 RETURN = """

plugins/modules/ec2_vpc_igw.py

@@ -20,27 +20,18 @@
       - The VPC ID for the VPC in which to manage the Internet Gateway.
     required: true
     type: str
-  tags:
-    description:
-      - A dict of tags to apply to the internet gateway.
-      - To remove all tags set I(tags={}) and I(purge_tags=true).
-    aliases: [ 'resource_tags' ]
-    type: dict
-  purge_tags:
-    description:
-      - Remove tags not listed in I(tags).
-    type: bool
-    default: true
-    version_added: 1.3.0
   state:
     description:
       - Create or terminate the IGW
     default: present
     choices: [ 'present', 'absent' ]
     type: str
+notes:
+- Support for I(purge_tags) was added in release 1.3.0.
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags
 '''
 
 EXAMPLES = '''

plugins/modules/ec2_vpc_nat_gateway.py

@@ -47,19 +47,6 @@
     required: false
     default: false
     type: bool
-  tags:
-    description:
-      - A dict of tags to apply to the NAT gateway.
-      - To remove all tags set I(tags={}) and I(purge_tags=true).
-    aliases: [ 'resource_tags' ]
-    type: dict
-    version_added: 1.4.0
-  purge_tags:
-    description:
-      - Remove tags not listed in I(tags).
-    type: bool
-    default: true
-    version_added: 1.4.0
   release_eip:
     description:
       - Deallocate the EIP from the VPC.
@@ -88,9 +75,12 @@
   - Jon Hadfield (@jonhadfield)
   - Karen Cheng (@Etherdaemon)
   - Alina Buzachis (@alinabuzachis)
+notes:
+  - Support for I(tags) and I(purge_tags) was added in release 1.4.0.
 extends_documentation_fragment:
-- amazon.aws.aws
-- amazon.aws.ec2
+  - amazon.aws.aws
+  - amazon.aws.ec2
+  - amazon.aws.tags
 '''
 
 EXAMPLES = r'''

plugins/modules/ec2_vpc_subnet.py

@@ -37,11 +37,6 @@
       - If set, allows to create subnet in an Outpost.
       - To specify outpost_arn, availability zone of Outpost subnet must be specified.
     type: str
-  tags:
-    description:
-      - "A dict of tags to apply to the subnet. Any tags currently applied to the subnet and not present here will be removed."
-    aliases: [ 'resource_tags' ]
-    type: dict
   state:
     description:
       - "Create or remove the subnet."
@@ -73,15 +68,10 @@
       - "Number of seconds to wait for subnet to become available I(wait=True)."
     default: 300
     type: int
-  purge_tags:
-    description:
-      - Whether or not to remove tags that do not appear in the I(tags) list.
-    type: bool
-    default: true
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
-
+- amazon.aws.tags
 '''
 
 EXAMPLES = '''

plugins/modules/elb_classic_lb.py

@@ -275,26 +275,16 @@
       - A maximum of 600 seconds (10 minutes) is allowed.
     type: int
     default: 180
-  tags:
-    description:
-      - A dictionary of tags to apply to the ELB.
-      - To delete all tags supply an empty dict (C({})) and set
-        I(purge_tags=true).
-    type: dict
-  purge_tags:
-    description:
-      - Whether to remove existing tags that aren't passed in the I(tags) parameter.
-    type: bool
-    default: true
-    version_added: 2.1.0
 
 notes:
 - The ec2_elb fact previously set by this module was deprecated in release 2.1.0 and since release
   4.0.0 is no longer set.
+- Support for I(purge_tags) was added in release 2.1.0.
 
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags
 '''
 
 EXAMPLES = """
@@ -2112,7 +2102,7 @@ def main():
         access_logs=dict(type='dict', options=access_log_spec),
         wait=dict(default=False, type='bool'),
         wait_timeout=dict(default=180, type='int'),
-        tags=dict(type='dict'),
+        tags=dict(type='dict', aliases=['resource_tags']),
         purge_tags=dict(default=True, type='bool'),
     )
 

plugins/modules/s3_bucket.py

@@ -70,15 +70,6 @@
     default: present
     choices: [ 'present', 'absent' ]
     type: str
-  tags:
-    description:
-      - Tags dict to apply to bucket.
-    type: dict
-  purge_tags:
-    description:
-      - Whether to remove tags that aren't present in the I(tags) parameter.
-    type: bool
-    default: True
   versioning:
     description:
       - Whether versioning is enabled or disabled (note that once versioning is enabled, it can only be suspended).
@@ -166,6 +157,7 @@
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags
 
 notes:
     - If C(requestPayment), C(policy), C(tagging) or C(versioning)
@@ -1011,7 +1003,7 @@ def main():
         requester_pays=dict(type='bool'),
         s3_url=dict(aliases=['S3_URL'], deprecated_aliases=[dict(name='S3_URL', version='5.0.0', collection_name='amazon.aws')]),
         state=dict(default='present', choices=['present', 'absent']),
-        tags=dict(type='dict'),
+        tags=dict(type='dict', aliases=['resource_tags']),
         purge_tags=dict(type='bool', default=True),
         versioning=dict(type='bool'),
         ceph=dict(default=False, type='bool'),