ec2_tag - Deprecate the use of state=list (#66840)

* ec2_tag - Deprecate the use of state=list

* Update lib/ansible/modules/cloud/amazon/ec2_tag.py

* Add changelog and porting_guide entries

Co-authored-by: flowerysong <junk+github@flowerysong.com>

changelogs/fragments/66840-ec2_tag-deprecate-list.yaml

@@ -0,0 +1,2 @@
+deprecated_features:
+- 'ec2_tag: deprecate the `list` option in favor of ec2_tag_info'

docs/docsite/rst/porting_guides/porting_guide_2.10.rst

@@ -71,6 +71,7 @@ The following functionality will be removed in Ansible 2.14. Please update updat
 * :ref:`ec2_key <ec2_key_module>`: the ``wait`` option will be removed. It has had no effect since Ansible 2.5.
 * :ref:`ec2_key <ec2_key_module>`: the ``wait_timeout`` option will be removed. It has had no effect since Ansible 2.5.
 * :ref:`ec2_lc <ec2_lc_module>`: the ``associate_public_ip_address`` option will be removed. It has always been ignored by the module.
+* :ref:`ec2_tag <ec2_tag_module>`: Support for ``list`` as a state has been deprecated.  The ``ec2_tag_info`` can be used to fetch the tags on an EC2 resource.
 * :ref:`iam_policy <iam_policy_module>`: the ``policy_document`` option will be removed. To maintain the existing behavior use the ``policy_json`` option and read the file with the ``lookup`` plugin.
 * :ref:`redfish_config <redfish_config_module>`: the ``bios_attribute_name`` and ``bios_attribute_value`` options will be removed. To maintain the existing behavior use the ``bios_attributes`` option instead.
 * :ref:`clc_aa_policy <clc_aa_policy_module>`: the ``wait`` parameter will be removed. It has always been ignored by the module.

lib/ansible/modules/cloud/amazon/ec2_tag.py

@@ -16,8 +16,9 @@ DOCUMENTATION = '''
 module: ec2_tag
 short_description: create and remove tags on ec2 resources
 description:
-    - Creates, removes and lists tags for any EC2 resource.  The resource is referenced by its resource id (e.g. an instance being i-XXXXXXX).
-      It is designed to be used with complex args (tags), see the examples.
+    - Creates, modifies and removes tags for any EC2 resource.
+    - Resources are referenced by their resource id (for example, an instance being i-XXXXXXX, a VPC being vpc-XXXXXXX).
+    - This module is designed to be used with complex args (tags), see the examples.
 version_added: "1.3"
 requirements: [ "boto3", "botocore" ]
 options:
@@ -28,14 +29,17 @@ options:
     type: str
   state:
     description:
-      - Whether the tags should be present or absent on the resource. Use list to interrogate the tags of an instance.
+      - Whether the tags should be present or absent on the resource.
+      - The use of I(state=list) to interrogate the tags of an instance has been
+        deprecated and will be removed in Anisble 2.14.  The 'list'
+        functionality has been moved to a dedicated module M(ec2_tag_info).
     default: present
     choices: ['present', 'absent', 'list']
     type: str
   tags:
     description:
       - A dictionary of tags to add or remove from the resource.
-      - If the value provided for a tag is null and I(state=absent), the tag will be removed regardless of its current value.
+      - If the value provided for a key is not set and I(state=absent), the tag will be removed regardless of its current value.
       - Required when I(state=present) or I(state=absent).
     type: dict
   purge_tags:
@@ -43,7 +47,7 @@ options:
       - Whether unspecified tags should be removed from the resource.
       - Note that when combined with I(state=absent), specified tags with non-matching values are not purged.
     type: bool
-    default: no
+    default: false
     version_added: '2.7'
 
 author:
@@ -74,13 +78,6 @@ EXAMPLES = '''
       Env: production
   loop: '{{ ec2_vol.volumes }}'
 
-- name: Retrieve all tags on an instance
-  ec2_tag:
-    region: eu-west-1
-    resource: i-xxxxxxxxxxxxxxxxx
-    state: list
-  register: ec2_tags
-
 - name: Remove the Env tag
   ec2_tag:
     region: eu-west-1
@@ -162,6 +159,8 @@ def main():
     current_tags = get_tags(ec2, module, resource)
 
     if state == 'list':
+        module.deprecate(
+            'Using the "list" state has been deprecated.  Please use the ec2_tag_info module instead', version='2.14')
         module.exit_json(changed=False, tags=current_tags)
 
     add_tags, remove = compare_aws_tags(current_tags, tags, purge_tags=purge_tags)