Deprecate state=list in ec2_vol

changelogs/fragments/108-ec2_vol-deprecate-list.yml

@@ -0,0 +1,3 @@
+deprecated_features:
+- 'ec2_vol: deprecate the `list` option in favor of ec2_vol_info'
+

plugins/modules/ec2_vol.py

@@ -78,7 +78,10 @@
     default: true
   state:
     description:
-      - Whether to ensure the volume is present or absent, or to list existing volumes (The C(list) option was added in version 1.8).
+      - Whether to ensure the volume is present or absent.
+      - The use of I(state=list) to interrogate the volume has been deprecated
+        and will be removed after 2022-06-01.  The 'list' functionality
+        has been moved to a dedicated module M(amazon.aws.ec2_vol_info).
     default: present
     choices: ['absent', 'present', 'list']
     type: str
@@ -520,6 +523,10 @@ def main():
     state = module.params.get('state')
     tags = module.params.get('tags')
 
+    if state == 'list':
+        module.deprecate(
+            'Using the "list" state has been deprecated.  Please use the ec2_vol_info module instead', date='2022-06-01', collection_name='amazon.aws')
+
     # 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_vol_info.py

@@ -51,9 +51,66 @@
 
 '''
 
-# TODO: Disabled the RETURN as it was breaking docs building. Someone needs to
-# fix this
-RETURN = '''# '''
+RETURN = '''
+volumes:
+    description: Volumes that match the provided filters. Each element consists of a dict with all the information related to that volume.
+    type: list
+    elements: dict
+    returned: always
+    contains:
+        attachment_set:
+            description: Information about the volume attachments.
+            type: dict
+            sample: {
+                "attach_time": "2015-10-23T00:22:29.000Z",
+                "deleteOnTermination": "false",
+                "device": "/dev/sdf",
+                "instance_id": "i-8356263c",
+                "status": "attached"
+            }
+        create_time:
+            description: The time stamp when volume creation was initiated.
+            type: str
+            sample: "2015-10-21T14:36:08.870Z"
+        encrypted:
+            description: Indicates whether the volume is encrypted.
+            type: bool
+            sample: False
+        id:
+            description: The ID of the volume.
+            type: str
+            sample: "vol-35b333d9"
+        iops:
+            description: The number of I/O operations per second (IOPS) that the volume supports.
+            type: int
+            sample: null
+        size:
+            description: The size of the volume, in GiBs.
+            type: int
+            sample: 1
+        snapshot_id:
+            description: The snapshot from which the volume was created, if applicable.
+            type: str
+            sample: ""
+        status:
+            description: The volume state.
+            type: str
+            sample: "in-use"
+        tags:
+            description: Any tags assigned to the volume.
+            type: dict
+            sample: {
+                env: "dev"
+                }
+        type:
+            description: The volume type. This can be gp2, io1, st1, sc1, or standard.
+            type: str
+            sample: "standard"
+        zone:
+            description:
+            type: str
+            sample: "us-east-1b"
+'''
 
 import traceback