Fix rds_snapshot_info return values in docs (#2354) (#2438)

This is a backport of PR #2354 as merged into main (786c4b7).
SUMMARY
There are some inaccuracies and inconsistencies in the documentation for rds_snapshot_info - specifically, missing return types and fields. This PR corrects these issues, and updates their descriptions to more closely mirror the official AWS documentation.
ISSUE TYPE

Docs Pull Request

COMPONENT NAME
rds_snapshot_info
ADDITIONAL INFORMATION
The documentation for rds_snapshot_info show that the module returns cluster_snapshots, but this is only true when db_cluster_identifier or db_cluster_snapshot_identifier is defined. The module returns snapshots when db_snapshot_identifier or db_instance_identifier is defined instead. This appears to have been introduced in amazon.aws 8.2.0 (specifically, PR #2156 - I have mirrored many of the formatting changes done in that PR when re-adding the snapshots object).
Several fields were also missing from the return objects for both snapshots and cluster_snapshots, so those have been added. Some descriptions also varied for identical fields in snapshots and cluster_snapshots, so all descriptions have been updated to match the AWS CLI documentation pages for describe-db-snapshots and describe-db-cluster-snapshots.

Reviewed-by: Helen Bailey <[email protected]>
Reviewed-by: Bikouo Aubin
Reviewed-by: GomathiselviS <[email protected]>

plugins/modules/rds_snapshot_info.py

@@ -69,100 +69,260 @@
 """
 
 RETURN = r"""
+snapshots:
+  description: List of non-clustered snapshots.
+  returned: When cluster parameters are not passed.
+  type: complex
+  contains:
+    allocated_storage:
+      description: The allocated storage size in gibibytes (GiB).
+      returned: always
+      type: int
+      sample: 10
+    availability_zone:
+      description: The name of the Availability Zone the DB instance was located in at the time of the DB snapshot.
+      returned: always
+      type: str
+      sample: "us-west-2b"
+    db_instance_identifier:
+      description: The DB instance identifier of the DB instance this DB snapshot was created from.
+      returned: always
+      type: str
+      sample: "hello-world-rds"
+    db_snapshot_arn:
+      description: The Amazon Resource Name (ARN) for the DB snapshot.
+      returned: always
+      type: str
+      sample: "arn:aws:rds:us-west-2:123456789012:snapshot:rds:hello-world-rds-us1-2018-05-16-04-03"
+    db_snapshot_identifier:
+      description: The identifier for the DB snapshot.
+      returned: always
+      type: str
+      sample: "rds:hello-world-rds-us1-2018-05-16-04-03"
+    dbi_resource_id:
+      description: The identifier for the source DB instance, which can't be changed and which is unique to an Amazon Web Services Region.
+      returned: always
+      type: str
+      sample: "db-ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    dedicated_log_volume:
+      description: Whether the DB instance has a dedicated log volume (DLV) enabled.
+      returned: always
+      type: bool
+      sample: false
+    encrypted:
+      description: Whether the DB snapshot is encrypted.
+      returned: always
+      type: bool
+      sample: true
+    engine:
+      description: The name of the database engine.
+      returned: always
+      type: str
+      sample: "postgres"
+    engine_version:
+      description: The version of the database engine.
+      returned: always
+      type: str
+      sample: "9.5.10"
+    iam_database_authentication_enabled:
+      description: Whether mapping of Amazon Web Services Identity and Access Management (IAM) accounts to database accounts is enabled.
+      returned: always
+      type: bool
+      sample: false
+    instance_create_time:
+      description: The time when the DB instance, from which the snapshot was taken, was created.
+      returned: always
+      type: str
+      sample: "2017-10-10T04:00:07.434000+00:00"
+    iops:
+      description: The Provisioned IOPS (I/O operations per second) value of the DB instance at the time of the snapshot.
+      returned: always
+      type: int
+      sample: 3000
+    kms_key_id:
+      description: The Amazon Web Services KMS key identifier for the encrypted DB snapshot.
+      returned: when encrypted is true
+      type: str
+      sample: "arn:aws:kms:us-west-2:123456789012:key/abcd1234-1234-aaaa-0000-1234567890ab"
+    license_model:
+      description: License model information for the restored DB instance.
+      returned: always
+      type: str
+      sample: "postgresql-license"
+    master_username:
+      description: The master username for the DB snapshot.
+      returned: always
+      type: str
+      sample: "dbadmin"
+    multi_tenant:
+      description: Whether the snapshot is of a DB instance using the multi-tenant configuration (TRUE) or the single-tenant configuration (FALSE).
+      returned: always
+      type: bool
+      sample: false
+    option_group_name:
+      description: The option group name for the DB snapshot.
+      returned: always
+      type: str
+      sample: "default:postgres-9-5"
+    original_snapshot_create_time:
+      description: The time of the CreateDBSnapshot operation. Doesn't change when the snapshot is copied.
+      returned: always
+      type: str
+      sample: "2017-10-10T04:00:07.434000+00:00"
+    percent_progress:
+      description: The percentage of the estimated data that has been transferred.
+      returned: always
+      type: int
+      sample: 100
+    port:
+      description: The port that the database engine was listening on at the time of the snapshot.
+      returned: always
+      type: int
+      sample: 0
+    snapshot_create_time:
+      description: When the snapshot was taken.
+      returned: always
+      type: str
+      sample: "2018-05-16T04:03:33.871000+00:00"
+    snapshot_target:
+      description: "Where manual snapshots are stored: Amazon Web Services Outposts or the Amazon Web Services Region."
+      returned: always
+      type: str
+      sample: "region"
+    snapshot_type:
+      description: The type of the DB snapshot.
+      returned: always
+      type: str
+      sample: "automated"
+    status:
+      description: The status of this DB snapshot.
+      returned: always
+      type: str
+      sample: "available"
+    storage_throughput:
+      description: The storage throughput for the DB snapshot.
+      returned: always
+      type: int
+      sample: 500
+    storage_type:
+      description: The storage type associated with DB snapshot.
+      returned: always
+      type: str
+      sample: "gp2"
+    tags:
+      description: Tags of the snapshot.
+      returned: when snapshot is not shared.
+      type: complex
+      contains: {}
+    vpc_id:
+      description: The VPC ID associated with the DB snapshot.
+      returned: always
+      type: str
+      sample: "vpc-abcd1234"
 cluster_snapshots:
   description: List of cluster snapshots.
-  returned: always
+  returned: When cluster parameters are passed.
   type: complex
   contains:
     allocated_storage:
-      description: How many gigabytes of storage are allocated.
+      description: The allocated storage size in gibibytes (GiB).
       returned: always
       type: int
       sample: 1
     availability_zones:
-      description: The availability zones of the database from which the snapshot was taken.
+      description: The list of Availability Zones (AZs) where instances in the DB cluster snapshot can be restored.
       returned: always
       type: list
       sample:
-      - ca-central-1a
-      - ca-central-1b
+      - "ca-central-1a"
+      - "ca-central-1b"
     cluster_create_time:
-      description: Date and time the cluster was created.
+      description: The time when the DB cluster was created.
       returned: always
       type: str
       sample: "2018-05-17T00:13:40.223000+00:00"
     db_cluster_identifier:
-      description: Database cluster identifier.
+      description: The DB cluster identifier of the DB cluster that this DB cluster snapshot was created from.
       returned: always
       type: str
       sample: "test-aurora-cluster"
+    db_cluster_resource_id:
+      description: The resource ID of the DB cluster that this DB cluster snapshot was created from.
+      returned: always
+      type: str
+      sample: "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ"
     db_cluster_snapshot_arn:
-      description: ARN of the database snapshot.
+      description: The Amazon Resource Name (ARN) for the DB cluster snapshot.6
       returned: always
       type: str
       sample: "arn:aws:rds:ca-central-1:123456789012:cluster-snapshot:test-aurora-snapshot"
     db_cluster_snapshot_identifier:
-      description: Snapshot identifier.
+      description: The identifier for the DB cluster snapshot.
       returned: always
       type: str
       sample: "test-aurora-snapshot"
     engine:
-      description: Database engine.
+      description: The name of the database engine for this DB cluster snapshot.
       returned: always
       type: str
       sample: "aurora"
+    engine_mode:
+      description: The engine mode of the database engine for this DB cluster snapshot.
+      returned: always
+      type: str
+      sample: "provisioned"
     engine_version:
-      description: Database engine version.
+      description: The version of the database engine for this DB cluster snapshot.
       returned: always
       type: str
       sample: "5.6.10a"
     iam_database_authentication_enabled:
-      description: Whether database authentication through IAM is enabled.
+      description: Whether mapping of Amazon Web Services Identity and Access Management (IAM) accounts to database accounts is enabled.
       returned: always
       type: bool
       sample: false
     kms_key_id:
-      description: ID of the KMS Key encrypting the snapshot.
-      returned: always
+      description: the Amazon Web Services KMS key identifier for the encrypted DB cluster snapshot.
+      returned: when storage_encrypted is true
       type: str
-      sample: "arn:aws:kms:ca-central-1:123456789012:key/abcd1234-abcd-1111-aaaa-0123456789ab"
+      sample: "arn:aws:kms:us-west-2:123456789012:key/abcd1234-1234-aaaa-0000-1234567890ab"
     license_model:
-      description: License model.
+      description: The license model information for this DB cluster snapshot.
       returned: always
       type: str
       sample: "aurora"
     master_username:
-      description: Database master username.
+      description: The master username for this DB cluster snapshot.
       returned: always
       type: str
       sample: "shertel"
     percent_progress:
-      description: Percent progress of snapshot.
+      description: The percentage of the estimated data that has been transferred.
       returned: always
       type: int
       sample: 0
     port:
-      description: Database port.
+      description: The port that the DB cluster was listening on at the time of the snapshot.
       returned: always
       type: int
       sample: 0
     snapshot_create_time:
-      description: Date and time when the snapshot was created.
+      description: The time when the snapshot was taken.
       returned: always
       type: str
       sample: "2018-05-17T00:23:23.731000+00:00"
     snapshot_type:
-      description: Type of snapshot.
+      description: The type of the DB cluster snapshot.
       returned: always
       type: str
       sample: "manual"
     status:
-      description: Status of snapshot.
+      description: The status of this DB cluster snapshot.
       returned: always
       type: str
       sample: "creating"
     storage_encrypted:
-      description: Whether the snapshot is encrypted.
+      description: Indicates whether the DB cluster snapshot is encrypted.
       returned: always
       type: bool
       sample: true
@@ -172,7 +332,7 @@
       type: complex
       contains: {}
     vpc_id:
-      description: VPC of the database.
+      description: The VPC ID associated with the DB cluster snapshot.
       returned: always
       type: str
       sample: "vpc-abcd1234"