Tagging - remove default empty dict where purge_tags default is False (…

…#1186)

Tagging - remove default empty dict where purge_tags default is False

Depends-On: ansible-collections/amazon.aws#844
SUMMARY

Deprecate purge_tags=False
Remove default of empty dict for tags

ISSUE TYPE

Feature Pull Request

COMPONENT NAME
plugins/modules/aws_kms.py
plugins/modules/cloudfront_distribution.py
plugins/modules/ec2_vpc_vpn.py
plugins/modules/rds_param_group.py
ADDITIONAL INFORMATION

Reviewed-by: Markus Bergholz <[email protected]>
Reviewed-by: Alina Buzachis <None>

changelogs/fragments/1186-tagging.yml

@@ -0,0 +1,14 @@
+minor_changes:
+- aws_kms - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/community.aws/pull/1185).
+- aws_kms - the default value for ``tags`` has been updated, to remove all tags the ``tags`` parameter must be explicitly set to the empty dict ``{}`` and ``purge_tags`` to ``True`` (https://github.com/ansible-collections/community.aws/pull/1183).
+- cloudfront_distribution - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/community.aws/pull/1185).
+- cloudfront_distribution - the default value for ``tags`` has been updated, to remove all tags the ``tags`` parameter must be explicitly set to the empty dict ``{}`` and ``purge_tags`` to ``True`` (https://github.com/ansible-collections/community.aws/pull/1183).
+- ec2_vpc_vpn - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/community.aws/pull/1185).
+- ec2_vpc_vpn - the default value for ``tags`` has been updated, to remove all tags the ``tags`` parameter must be explicitly set to the empty dict ``{}`` and ``purge_tags`` to ``True`` (https://github.com/ansible-collections/community.aws/pull/1183).
+- rds_param_group - ``resource_tags`` has been added as an alias for the ``tags`` parameter (https://github.com/ansible-collections/community.aws/pull/1185).
+- rds_param_group - the default value for ``tags`` has been updated, to remove all tags the ``tags`` parameter must be explicitly set to the empty dict ``{}`` and ``purge_tags`` to ``True`` (https://github.com/ansible-collections/community.aws/pull/1183).
+deprecated_features:
+- aws_kms - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True``.
+- cloudfront_distribution - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True``.
+- ec2_vpc_vpn - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True``.
+- rds_param_group - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True``.

plugins/modules/aws_kms.py

@@ -12,7 +12,7 @@
 version_added: 1.0.0
 short_description: Perform various KMS management tasks
 description:
-     - Manage role/user access to a KMS key. Not designed for encrypting/decrypting.
+  - Manage role/user access to a KMS key. Not designed for encrypting/decrypting.
 options:
   alias:
     description: An alias for a key. For safety, even though KMS does not require keys
@@ -114,9 +114,6 @@
       A description of the CMK. Use a description that helps you decide
       whether the CMK is appropriate for a task.
     type: str
-  tags:
-    description: A dictionary of tags to apply to a key.
-    type: dict
   pending_window:
     description:
     - The number of days between requesting deletion of the CMK and when it will actually be deleted.
@@ -126,11 +123,6 @@
     type: int
     aliases: ['deletion_delay']
     version_added: 1.4.0
-  purge_tags:
-    description: Whether the I(tags) argument should cause tags not in the list to
-      be removed.
-    default: False
-    type: bool
   purge_grants:
     description: Whether the I(grants) argument should cause grants not in the list to
       be removed.
@@ -196,8 +188,9 @@
   - Will Thames (@willthames)
   - Mark Chappell (@tremble)
 extends_documentation_fragment:
-- amazon.aws.aws
-- amazon.aws.ec2
+  - amazon.aws.aws
+  - amazon.aws.ec2
+  - amazon.aws.tags.deprecated_purge
 
 
 notes:
@@ -809,6 +802,9 @@ def update_description(connection, module, key, description):
 
 
 def update_tags(connection, module, key, desired_tags, purge_tags):
+    if desired_tags is None:
+        return False
+
     # purge_tags needs to be explicitly set, so an empty tags list means remove
     # all tags
 
@@ -933,8 +929,13 @@ def update_key(connection, module, key):
 def create_key(connection, module):
     key_usage = module.params.get('key_usage')
     key_spec = module.params.get('key_spec')
+    tags_list = ansible_dict_to_boto3_tag_list(
+        module.params['tags'] or {},
+        # KMS doesn't use "Key" and "Value" as other APIs do.
+        tag_name_key_name='TagKey', tag_value_key_name='TagValue'
+    )
     params = dict(BypassPolicyLockoutSafetyCheck=False,
-                  Tags=ansible_dict_to_boto3_tag_list(module.params['tags'], tag_name_key_name='TagKey', tag_value_key_name='TagValue'),
+                  Tags=tags_list,
                   KeyUsage=key_usage,
                   CustomerMasterKeySpec=key_spec,
                   Origin='AWS_KMS')
@@ -1148,8 +1149,8 @@ def main():
         key_id=dict(aliases=['key_arn']),
         description=dict(),
         enabled=dict(type='bool', default=True),
-        tags=dict(type='dict', default={}),
-        purge_tags=dict(type='bool', default=False),
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
         grants=dict(type='list', default=[], elements='dict'),
         policy=dict(type='json'),
         purge_grants=dict(type='bool', default=False),
@@ -1170,6 +1171,14 @@ def main():
 
     kms = module.client('kms')
 
+    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='community.aws')
+        module.params['purge_tags'] = False
+
     module.deprecate("The 'policies' return key is deprecated and will be replaced by 'key_policies'. Both values are returned for now.",
                      date='2024-05-01', collection_name='community.aws')
 

plugins/modules/cloudfront_distribution.py

@@ -12,19 +12,19 @@
 version_added: 1.0.0
 module: cloudfront_distribution
 
-short_description: Create, update and delete AWS CloudFront distributions.
+short_description: Create, update and delete AWS CloudFront distributions
 
 description:
-    - Allows for easy creation, updating and deletion of CloudFront distributions.
+  - Allows for easy creation, updating and deletion of CloudFront distributions.
 
 author:
   - Willem van Ketwich (@wilvk)
   - Will Thames (@willthames)
 
 extends_documentation_fragment:
-- amazon.aws.aws
-- amazon.aws.ec2
-
+  - amazon.aws.aws
+  - amazon.aws.ec2
+  - amazon.aws.tags.deprecated_purge
 
 options:
 
@@ -58,21 +58,6 @@
           C(YYYY-MM-DDTHH:MM:SS.ffffff).
       type: str
 
-    tags:
-      description:
-        - Should be input as a dict of key-value pairs.
-        - "Note that numeric keys or values must be wrapped in quotes. e.g. C(Priority: '1')"
-      type: dict
-
-    purge_tags:
-      description:
-        - Specifies whether existing tags will be removed before adding new tags.
-        - When I(purge_tags=yes), existing tags are removed and I(tags) are added, if specified.
-          If no tags are specified, it removes all existing tags for the distribution.
-        - When I(purge_tags=no), existing tags are kept and I(tags) are added, if specified.
-      default: false
-      type: bool
-
     alias:
       description:
         - The name of an alias (CNAME) that is used in a distribution. This is used to effectively reference a distribution by its alias as an alias can only
@@ -1492,6 +1477,8 @@ def list_tags_for_resource(client, module, arn):
 
 
 def update_tags(client, module, existing_tags, valid_tags, purge_tags, arn):
+    if valid_tags is None:
+        return False
     changed = False
     to_add, to_remove = compare_aws_tags(existing_tags, valid_tags, purge_tags)
     if to_remove:
@@ -2121,8 +2108,8 @@ def main():
         comment=dict(),
         distribution_id=dict(),
         e_tag=dict(),
-        tags=dict(type='dict', default={}),
-        purge_tags=dict(type='bool', default=False),
+        tags=dict(type='dict', aliases=['resource_tags']),
+        purge_tags=dict(type='bool'),
         alias=dict(),
         aliases=dict(type='list', default=[], elements='str'),
         purge_aliases=dict(type='bool', default=False),
@@ -2161,6 +2148,14 @@ def main():
         ]
     )
 
+    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='community.aws')
+        module.params['purge_tags'] = False
+
     client = module.client('cloudfront', retry_decorator=AWSRetry.jittered_backoff())
 
     validation_mgr = CloudFrontValidationManager(module)
@@ -2239,7 +2234,7 @@ def main():
 
     if create:
         config['CallerReference'] = validation_mgr.validate_caller_reference(caller_reference)
-        result = create_distribution(client, module, config, ansible_dict_to_boto3_tag_list(tags))
+        result = create_distribution(client, module, config, ansible_dict_to_boto3_tag_list(tags or {}))
         result = camel_dict_to_snake_dict(result)
         result['tags'] = list_tags_for_resource(client, module, result['arn'])
 

plugins/modules/ec2_vpc_vpn.py

@@ -10,14 +10,16 @@
 ---
 module: ec2_vpc_vpn
 version_added: 1.0.0
-short_description: Create, modify, and delete EC2 VPN connections.
+short_description: Create, modify, and delete EC2 VPN connections
 description:
   - This module creates, modifies, and deletes VPN connections. Idempotence is achieved by using the filters
     option or specifying the VPN connection identifier.
 extends_documentation_fragment:
-- amazon.aws.ec2
-- amazon.aws.aws
-author: "Sloane Hertel (@s-hertel)"
+  - amazon.aws.ec2
+  - amazon.aws.aws
+  - amazon.aws.tags.deprecated_purge
+author:
+  - "Sloane Hertel (@s-hertel)"
 options:
   state:
     description:
@@ -44,15 +46,6 @@
     description:
       - The ID of the VPN connection. Required to modify or delete a connection if the filters option does not provide a unique match.
     type: str
-  tags:
-    description:
-      - Tags to attach to the VPN connection.
-    type: dict
-  purge_tags:
-    description:
-      - Whether or not to delete VPN connections tags that are associated with the connection but not specified in the task.
-    type: bool
-    default: false
   static_only:
     description:
       - Indicates whether the VPN connection uses static routes only. Static routes must be used for devices that don't support BGP.
@@ -580,8 +573,12 @@ def check_for_update(connection, module_params, vpn_connection_id):
 
     # Get changes to tags
     current_tags = boto3_tag_list_to_ansible_dict(current_attrs.get('tags', []), u'key', u'value')
-    tags_to_add, changes['tags_to_remove'] = compare_aws_tags(current_tags, tags, purge_tags)
-    changes['tags_to_add'] = ansible_dict_to_boto3_tag_list(tags_to_add)
+    if tags is None:
+        changes['tags_to_remove'] = []
+        changes['tags_to_add'] = []
+    else:
+        tags_to_add, changes['tags_to_remove'] = compare_aws_tags(current_tags, tags, purge_tags)
+        changes['tags_to_add'] = ansible_dict_to_boto3_tag_list(tags_to_add)
     # Get changes to routes
     if 'Routes' in vpn_connection:
         current_routes = [route['DestinationCidrBlock'] for route in vpn_connection['Routes']]
@@ -766,13 +763,13 @@ def main():
         state=dict(type='str', default='present', choices=['present', 'absent']),
         filters=dict(type='dict', default={}),
         vpn_gateway_id=dict(type='str'),
-        tags=dict(default={}, type='dict'),
+        tags=dict(type='dict', aliases=['resource_tags']),
         connection_type=dict(default='ipsec.1', type='str'),
         tunnel_options=dict(no_log=True, type='list', default=[], elements='dict'),
         static_only=dict(default=False, type='bool'),
         customer_gateway_id=dict(type='str'),
         vpn_connection_id=dict(type='str'),
-        purge_tags=dict(type='bool', default=False),
+        purge_tags=dict(type='bool'),
         routes=dict(type='list', default=[], elements='str'),
         purge_routes=dict(type='bool', default=False),
         wait_timeout=dict(type='int', default=600),
@@ -782,6 +779,14 @@ def main():
                               supports_check_mode=True)
     connection = module.client('ec2', retry_decorator=VPNRetry.jittered_backoff(retries=10))
 
+    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='community.aws')
+        module.params['purge_tags'] = False
+
     state = module.params.get('state')
     parameters = dict(module.params)
 

plugins/modules/rds_param_group.py

@@ -12,7 +12,7 @@
 version_added: 1.0.0
 short_description: manage RDS parameter groups
 description:
-     - Creates, modifies, and deletes RDS parameter groups.
+  - Creates, modifies, and deletes RDS parameter groups.
 options:
   state:
     description:
@@ -48,21 +48,13 @@
         or T for tera (1024^4), and these values will be expanded into the appropriate number before being set in the parameter group.
     aliases: [parameters]
     type: dict
-  tags:
-    description:
-      - Dictionary of tags to attach to the parameter group.
-    type: dict
-  purge_tags:
-    description:
-      - Whether or not to remove tags that do not appear in the C(tags) list.
-    type: bool
-    default: False
 author:
-    - "Scott Anderson (@tastychutney)"
-    - "Will Thames (@willthames)"
+  - "Scott Anderson (@tastychutney)"
+  - "Will Thames (@willthames)"
 extends_documentation_fragment:
-- amazon.aws.aws
-- amazon.aws.ec2
+  - amazon.aws.aws
+  - amazon.aws.ec2
+  - amazon.aws.tags.deprecated_purge
 
 '''
 
@@ -216,7 +208,10 @@ def update_parameters(module, connection):
 
 
 def update_tags(module, connection, group, tags):
+    if tags is None:
+        return False
     changed = False
+
     existing_tags = connection.list_tags_for_resource(aws_retry=True, ResourceName=group['DBParameterGroupArn'])['TagList']
     to_update, to_delete = compare_aws_tags(boto3_tag_list_to_ansible_dict(existing_tags),
                                             tags, module.params['purge_tags'])
@@ -319,15 +314,23 @@ def main():
         description=dict(),
         params=dict(aliases=['parameters'], type='dict'),
         immediate=dict(type='bool', aliases=['apply_immediately']),
-        tags=dict(type='dict', default={}),
-        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,
         required_if=[['state', 'present', ['description', 'engine']]],
         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='community.aws')
+        module.params['purge_tags'] = False
+
     try:
         conn = module.client('rds', retry_decorator=AWSRetry.jittered_backoff())
     except (botocore.exceptions.ClientError, botocore.exceptions.BotoCoreError) as e: