Update return block of ec2 modules (part 2) (#2079) (#2244)

This is a backport of PR #2079 as merged into main (9429894).
SUMMARY


Refer #1983
This PR aligns the RETURN blocks in the module documentation to accurately reflect what the module returns, ensuring consistency.
Modules updated:
ec2_snapshot ec2_snapshot_info ec2_spot_instance ec2_vol ec2_vpc_endpoint ec2_vpc_endpoint_info ec2_vpc_endpoint_service_info ec2_vpc_nat_gateway ec2_vpc_nat_gateway_info ec2_vpc_route_table ec2_vpc_subnet ec2_vpc_subnet_info
ISSUE TYPE


Docs Pull Request

COMPONENT NAME

ADDITIONAL INFORMATION

Reviewed-by: Mark Chappell

changelogs/fragments/update_return_block_ec2_2.yml

@@ -0,0 +1,3 @@
+---
+trivial:
+  - Update return block in the module documentation for ec2_snapshot ec2_snapshot_info ec2_spot_instance  ec2_vol ec2_vpc_endpoint ec2_vpc_endpoint_info ec2_vpc_endpoint_service_info ec2_vpc_nat_gateway ec2_vpc_nat_gateway_info ec2_vpc_route_table ec2_vpc_subnet ec2_vpc_subnet_info

plugins/modules/ec2_snapshot.py

@@ -185,6 +185,62 @@
     type: str
     returned: always
     sample: snap-01234567
+snapshots:
+    description: List of snapshots.
+    returned: always
+    type: list
+    elements: dict
+    contains:
+        description:
+            description: Description specified by the CreateSnapshotRequest that has been applied to all snapshots.
+            type: str
+            returned: always
+            sample: ""
+        encrypted:
+            description: Indicates whether the snapshot is encrypted.
+            type: bool
+            returned: always
+            sample: false
+        owner_id:
+            description: Account id used when creating this snapshot.
+            type: str
+            returned: always
+            sample: 123456
+        progress:
+            description: Progress this snapshot has made towards completing.
+            type: str
+            returned: always
+            sample: ""
+        snapshot_id:
+            description: Snapshot id that can be used to describe this snapshot.
+            type: str
+            returned: always
+            sample: snap-1234
+        start_time:
+            description: Time this snapshot was started. This is the same for all snapshots initiated by the same request.
+            type: str
+            returned: always
+            sample: "2024-05-07T14:29:24.523000+00:00"
+        state:
+            description: Current state of the snapshot.
+            type: str
+            returned: always
+            sample: pending
+        tags:
+            description: Tags associated with this snapshot.
+            type: dict
+            returned: always
+            sample: "{ 'Name': 'instance-name' }"
+        volume_id:
+            description: The ID of the volume that was used to create the snapshot.
+            type: str
+            returned: always
+            sample: vol-01234567
+        volume_size:
+            description: The size of the volume, in GiB.
+            type: int
+            returned: always
+            sample: 8
 tags:
     description: Any tags assigned to the snapshot.
     type: dict

plugins/modules/ec2_snapshot_info.py

@@ -117,90 +117,88 @@
     returned: success
     elements: dict
     contains:
-        snapshot_id:
-            description: The ID of the snapshot. Each snapshot receives a unique identifier when it is created.
+        create_volume_permissions:
+            description:
+              - The users and groups that have the permissions for creating volumes from the snapshot.
+              - The module will return empty list if the create volume permissions on snapshot are 'private'.
+            type: list
+            elements: dict
+            sample: [{"group": "all"}]
+        data_encryption_key_id:
+            description:
+              - The data encryption key identifier for the snapshot. This value is a unique identifier that
+                corresponds to the data encryption key that was used to encrypt the original volume or snapshot copy.
             type: str
             returned: always
-            sample: snap-01234567
-        volume_id:
-            description: The ID of the volume that was used to create the snapshot.
+            sample: "arn:aws:kms:ap-southeast-2:123456789012:key/74c9742a-a1b2-45cb-b3fe-abcdef123456"
+        description:
+            description: The description for the snapshot.
             type: str
             returned: always
-            sample: vol-01234567
-        state:
-            description: The snapshot state (completed, pending or error).
-            type: str
+            sample: "My important backup"
+        encrypted:
+            description: Indicates whether the snapshot is encrypted.
+            type: bool
             returned: always
-            sample: completed
-        state_message:
+            sample: "True"
+        kms_key_id:
             description:
-              - Encrypted Amazon EBS snapshots are copied asynchronously. If a snapshot copy operation fails (for example, if the proper
-                AWS Key Management Service (AWS KMS) permissions are not obtained) this field displays error state details to help you diagnose why the
-                error occurred.
+              - The full ARN of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to
+                protect the volume encryption key for the parent volume.
             type: str
-            returned: always
-            sample:
-        start_time:
-            description: The time stamp when the snapshot was initiated.
+            sample: "74c9742a-a1b2-45cb-b3fe-abcdef123456"
+        owner_id:
+            description: The AWS account ID of the EBS snapshot owner.
             type: str
             returned: always
-            sample: "2015-02-12T02:14:02+00:00"
+            sample: "123456789012"
         progress:
             description: The progress of the snapshot, as a percentage.
             type: str
             returned: always
             sample: "100%"
-        owner_id:
-            description: The AWS account ID of the EBS snapshot owner.
+        snapshot_id:
+            description: The ID of the snapshot. Each snapshot receives a unique identifier when it is created.
             type: str
             returned: always
-            sample: "123456789012"
-        description:
-            description: The description for the snapshot.
+            sample: snap-01234567
+        start_time:
+            description: The time stamp when the snapshot was initiated.
             type: str
             returned: always
-            sample: "My important backup"
-        volume_size:
-            description: The size of the volume, in GiB.
-            type: int
+            sample: "2015-02-12T02:14:02+00:00"
+        state:
+            description: The snapshot state (completed, pending or error).
+            type: str
             returned: always
-            sample: 8
-        owner_alias:
-            description: The AWS account alias (for example, amazon, self) or AWS account ID that owns the snapshot.
+            sample: completed
+        state_message:
+            description:
+              - Encrypted Amazon EBS snapshots are copied asynchronously. If a snapshot copy operation fails (for example, if the proper
+                AWS Key Management Service (AWS KMS) permissions are not obtained) this field displays error state details to help you diagnose why the
+                error occurred.
+            type: str
+            sample:
+        storage_tier:
+            description: The storage tier in which the snapshot is stored.
             type: str
             returned: always
-            sample: "123456789012"
+            sample: standard
         tags:
             description: Any tags assigned to the snapshot.
             type: dict
             returned: always
             sample: "{ 'my_tag_key': 'my_tag_value' }"
-        encrypted:
-            description: Indicates whether the snapshot is encrypted.
-            type: bool
-            returned: always
-            sample: "True"
-        kms_key_id:
-            description:
-              - The full ARN of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to
-                protect the volume encryption key for the parent volume.
+        volume_id:
+            description: The ID of the volume that was used to create the snapshot.
             type: str
             returned: always
-            sample: "74c9742a-a1b2-45cb-b3fe-abcdef123456"
-        data_encryption_key_id:
-            description:
-              - The data encryption key identifier for the snapshot. This value is a unique identifier that
-                corresponds to the data encryption key that was used to encrypt the original volume or snapshot copy.
-            type: str
+            sample: vol-01234567
+        volume_size:
+            description: The size of the volume, in GiB.
+            type: int
             returned: always
-            sample: "arn:aws:kms:ap-southeast-2:123456789012:key/74c9742a-a1b2-45cb-b3fe-abcdef123456"
-        create_volume_permissions:
-            description:
-              - The users and groups that have the permissions for creating volumes from the snapshot.
-              - The module will return empty list if the create volume permissions on snapshot are 'private'.
-            type: list
-            elements: dict
-            sample: [{"group": "all"}]
+            sample: 8
 next_token_id:
     description:
     - Contains the value returned from a previous paginated request where C(max_results) was used and the results exceeded the value of that parameter.

plugins/modules/ec2_spot_instance.py

@@ -394,14 +394,14 @@
             "message": "Your Spot request has been submitted for review, and is pending evaluation.",
             "update_time": "2021-08-23T22:59:12+00:00"
         },
+        "tags": {},
         "type": "one-time"
-
         }
 
 cancelled_spot_request:
     description: The spot instance request details that has been cancelled
-    returned: always
     type: str
+    returned: when cancellation is successful
     sample: 'Spot requests with IDs: sir-1234abcd have been cancelled'
 """
 

plugins/modules/ec2_vol.py

@@ -222,28 +222,79 @@
 volume:
     description: a dictionary containing detailed attributes of the volume
     returned: when success
-    type: str
-    sample: {
-        "attachment_set": [{
-            "attach_time": "2015-10-23T00:22:29.000Z",
-            "deleteOnTermination": "false",
-            "device": "/dev/sdf",
-            "instance_id": "i-8356263c",
-            "status": "attached"
-        }],
-        "create_time": "2015-10-21T14:36:08.870Z",
-        "encrypted": false,
-        "id": "vol-35b333d9",
-        "iops": null,
-        "size": 1,
-        "snapshot_id": "",
-        "status": "in-use",
-        "tags": {
-            "env": "dev"
-        },
-        "type": "standard",
-        "zone": "us-east-1b"
-    }
+    type: dict
+    contains:
+        attachment_set:
+            description:
+                - Information about the volume attachments.
+                - This was changed in version 2.0.0 from a dictionary to a list of dictionaries.
+            type: list
+            elements: dict
+            returned: when success
+            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
+            returned: when success
+            sample: "2015-10-21T14:36:08.870Z"
+        encrypted:
+            description: Indicates whether the volume is encrypted.
+            type: bool
+            returned: when success
+            sample: False
+        id:
+            description: The ID of the volume.
+            type: str
+            returned: when success
+            sample: "vol-35b333d9"
+        iops:
+            description: The number of I/O operations per second (IOPS) that the volume supports.
+            type: int
+            returned: when success
+            sample: null
+        size:
+            description: The size of the volume, in GiBs.
+            type: int
+            returned: when success
+            sample: 1
+        snapshot_id:
+            description: The snapshot from which the volume was created, if applicable.
+            type: str
+            returned: when success
+            sample: ""
+        status:
+            description: The volume state.
+            type: str
+            returned: when success
+            sample: "in-use"
+        tags:
+            description: Any tags assigned to the volume.
+            type: dict
+            returned: when success
+            sample: {
+                env: "dev"
+                }
+        type:
+            description: The volume type. This can be gp2, io1, st1, sc1, or standard.
+            type: str
+            returned: when success
+            sample: "standard"
+        zone:
+            description: The Availability Zone of the volume.
+            type: str
+            returned: when success
+            sample: "us-east-1b"
+        throughput:
+            description: The throughput that the volume supports, in MiB/s.
+            type: int
+            returned: when success
+            sample: 131
 """
 
 import time