Tagging - deprecate defaults of purge_tags=False

changelogs/fragments/846-tagging-deprecate.yml

@@ -0,0 +1,6 @@
+deprecated_features:
+- ec2_ami - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846).
+- ec2_key - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846).
+- ec2_vol - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846).
+- ec2_vpc_endpoint - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846).
+- ec2_vpc_route_table - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846).

plugins/modules/ec2_ami.py

@@ -123,14 +123,6 @@
       - Delete snapshots when deregistering the AMI.
     default: false
     type: bool
-  tags:
-    description:
-      - A dictionary of tags to add to the new image; '{"key":"value"}' and '{"key":"value","key":"value"}'
-    type: dict
-  purge_tags:
-    description: Whether to remove existing tags that aren't passed in the C(tags) parameter
-    default: false
-    type: bool
   launch_permissions:
     description:
       - Users and groups that should be able to launch the AMI. Expects dictionary with a key of user_ids and/or group_names. user_ids should
@@ -166,7 +158,7 @@
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
-
+- amazon.aws.tags.deprecated_purge
 '''
 
 # Thank you to iAcquire for sponsoring development of this module.
@@ -742,14 +734,14 @@ def main():
         no_reboot=dict(default=False, type='bool'),
         state=dict(default='present', choices=['present', 'absent']),
         device_mapping=dict(type='list', elements='dict', options=mapping_options),
-        tags=dict(type='dict'),
         launch_permissions=dict(type='dict'),
         image_location=dict(),
         enhanced_networking=dict(type='bool'),
         billing_products=dict(type='list', elements='str',),
         ramdisk_id=dict(),
         sriov_net_support=dict(),
-        purge_tags=dict(type='bool', default=False)
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
     )
 
     module = AnsibleAWSModule(
@@ -765,6 +757,14 @@ def main():
     if not any([module.params['image_id'], module.params['name']]):
         module.fail_json(msg="one of the following is required: name, image_id")
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='amazon.aws')
+        module.params['purge_tags'] = False
+
     connection = module.client('ec2', retry_decorator=AWSRetry.jittered_backoff())
 
     if module.params.get('state') == 'absent':

plugins/modules/ec2_key.py

@@ -38,17 +38,6 @@
     choices: [ present, absent ]
     default: 'present'
     type: str
-  tags:
-    description:
-      - A dictionary of tags to set on the key pair.
-    type: dict
-    version_added: 2.1.0
-  purge_tags:
-    description:
-      - Delete any tags not specified in I(tags).
-    default: false
-    type: bool
-    version_added: 2.1.0
   key_type:
     description:
       - The type of key pair to create.
@@ -62,10 +51,12 @@
       - rsa
       - ed25519
     version_added: 3.1.0
-
+notes:
+- Support for I(tags) and I(purge_tags) was added in release 2.1.0.
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags.deprecated_purge
 
 author:
   - "Vincent Viallet (@zbal)"
@@ -313,8 +304,8 @@ def main():
         key_material=dict(no_log=False),
         force=dict(type='bool', default=True),
         state=dict(default='present', choices=['present', 'absent']),
-        tags=dict(type='dict'),
-        purge_tags=dict(type='bool', default=False),
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
         key_type=dict(type='str', choices=['rsa', 'ed25519']),
     )
 
@@ -326,6 +317,14 @@ def main():
         supports_check_mode=True
     )
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='amazon.aws')
+        module.params['purge_tags'] = False
+
     ec2_client = module.client('ec2', retry_decorator=AWSRetry.jittered_backoff())
 
     name = module.params['name']

plugins/modules/ec2_vol.py

@@ -80,16 +80,6 @@
     default: present
     choices: ['absent', 'present']
     type: str
-  tags:
-    description:
-      - tag:value pairs to add to the volume after creation.
-    default: {}
-    type: dict
-  purge_tags:
-    description: Whether to remove existing tags that aren't passed in the I(tags) parameter
-    default: false
-    type: bool
-    version_added: 1.5.0
   modify_volume:
     description:
       - The volume won't be modified unless this key is C(true).
@@ -117,9 +107,12 @@
     type: str
     version_added: 3.1.0
 author: "Lester Wade (@lwade)"
+notes:
+- Support for I(purge_tags) was added in release 1.5.0.
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags.deprecated_purge
 '''
 
 EXAMPLES = '''
@@ -459,7 +452,7 @@ def create_volume(module, ec2_conn, zone):
     throughput = module.params.get('throughput')
     multi_attach = module.params.get('multi_attach')
     outpost_arn = module.params.get('outpost_arn')
-    tags = module.params.get('tags')
+    tags = module.params.get('tags') or {}
     name = module.params.get('name')
 
     volume = get_volume(module, ec2_conn)
@@ -715,11 +708,11 @@ def main():
         zone=dict(aliases=['availability_zone', 'aws_zone', 'ec2_zone']),
         snapshot=dict(),
         state=dict(default='present', choices=['absent', 'present']),
-        tags=dict(default={}, type='dict'),
+        tags=dict(type='dict', aliases=['resource_tags']),
         modify_volume=dict(default=False, type='bool'),
         throughput=dict(type='int'),
         outpost_arn=dict(type='str'),
-        purge_tags=dict(type='bool', default=False),
+        purge_tags=dict(type='bool'),
         multi_attach=dict(type='bool'),
     )
 
@@ -746,6 +739,14 @@ def main():
     throughput = module.params.get('throughput')
     multi_attach = module.params.get('multi_attach')
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='amazon.aws')
+        module.params['purge_tags'] = False
+
     # Ensure we have the zone or can get the zone
     if instance is None and zone is None and state == 'present':
         module.fail_json(msg="You must specify either instance or zone")

plugins/modules/ec2_vpc_endpoint.py

@@ -81,19 +81,6 @@
     default: present
     choices: [ "present", "absent" ]
     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).
-    type: dict
-    version_added: 1.5.0
-  purge_tags:
-    description:
-      - Delete any tags not specified in the task that are on the instance.
-        This means you have to specify all the desired tags on each task affecting an instance.
-    default: false
-    type: bool
-    version_added: 1.5.0
   wait:
     description:
       - When specified, will wait for either available status for state present.
@@ -130,9 +117,12 @@
     required: false
     type: str
 author: Karen Cheng (@Etherdaemon)
+notes:
+- Support for I(tags) and I(purge_tags) was added in release 1.5.0.
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
+- amazon.aws.tags.deprecated_purge
 
 '''
 
@@ -435,8 +425,8 @@ def main():
         route_table_ids=dict(type='list', elements='str'),
         vpc_endpoint_id=dict(),
         client_token=dict(no_log=False),
-        tags=dict(type='dict'),
-        purge_tags=dict(type='bool', default=False),
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
     )
     module = AnsibleAWSModule(
         argument_spec=argument_spec,
@@ -451,6 +441,14 @@ def main():
     # Validate Requirements
     state = module.params.get('state')
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='amazon.aws')
+        module.params['purge_tags'] = False
+
     if module.params.get('policy_file'):
         module.deprecate('The policy_file option has been deprecated and'
                          ' will be removed after 2022-12-01',

plugins/modules/ec2_vpc_route_table.py

@@ -25,9 +25,14 @@
     type: str
     version_added: 3.2.0
   lookup:
-    description: Look up route table by either tags or by route table ID. Non-unique tag lookup will fail.
-      If no tags are specified then no lookup for an existing route table is performed and a new
-      route table will be created. To change tags of a route table you must look up by id.
+    description:
+      - Look up route table by either I(tags) or by I(route_table_id).
+      - If I(lookup=tag) and I(tags) is not specified then no lookup for an
+        existing route table is performed and a new route table will be created.
+      - When using I(lookup=tag), multiple matches being found will result in
+        a failure and no changes will be made.
+      - To change the tags of a route table use I(lookup=id).
+      - I(vpc_id) must be specified when I(lookup=tag).
     default: tag
     choices: [ 'tag', 'id' ]
     type: str
@@ -43,10 +48,6 @@
     description: Purge existing subnets that are not found in subnets. Ignored unless the subnets option is supplied.
     default: True
     type: bool
-  purge_tags:
-    description: Purge existing tags that are not found in route table.
-    type: bool
-    default: False
   route_table_id:
     description:
     - The ID of the route table to update or delete.
@@ -73,21 +74,17 @@
       by either subnet ID, Name tag, or by a CIDR such as '10.0.0.0/24' or 'fd00::/8'.
     type: list
     elements: str
-  tags:
-    description: >
-      A dictionary of resource tags of the form: C({ tag1: value1, tag2: value2 }). Tags are
-      used to uniquely identify route tables within a VPC when the route_table_id is not supplied.
-    aliases: [ "resource_tags" ]
-    type: dict
   vpc_id:
     description:
     - VPC ID of the VPC in which to create the route table.
     - Required when I(state=present) or I(lookup=tag).
     type: str
+notes:
+- Tags are used to uniquely identify route tables within a VPC when the I(route_table_id) is not supplied.
 extends_documentation_fragment:
 - amazon.aws.aws
 - amazon.aws.ec2
-
+- amazon.aws.tags.deprecated_purge
 '''
 
 EXAMPLES = r'''
@@ -808,7 +805,7 @@ def main():
         propagating_vgw_ids=dict(type='list', elements='str'),
         purge_routes=dict(default=True, type='bool'),
         purge_subnets=dict(default=True, type='bool'),
-        purge_tags=dict(default=False, type='bool'),
+        purge_tags=dict(type='bool'),
         route_table_id=dict(),
         routes=dict(default=[], type='list', elements='dict'),
         state=dict(default='present', choices=['present', 'absent']),
@@ -823,6 +820,14 @@ def main():
                                            ['state', 'present', ['vpc_id']]],
                               supports_check_mode=True)
 
+    if module.params.get('purge_tags') is None:
+        module.deprecate(
+            'The purge_tags parameter currently defaults to False.'
+            ' For consistency across the collection, this default value'
+            ' will change to True in release 5.0.0.',
+            version='5.0.0', collection_name='amazon.aws')
+        module.params['purge_tags'] = False
+
     # The tests for RouteTable existing uses its own decorator, we can safely
     # retry on InvalidRouteTableID.NotFound
     retry_decorator = AWSRetry.jittered_backoff(retries=10, catch_extra_error_codes=['InvalidRouteTableID.NotFound'])