Fixed docs for cloud modules (#23745)

* Fixed docs for cloud modules * removed blank line in ec2_snapshot_facts
2025-07-22 12:50:22 -07:00 · 2017-04-27 12:01:11 +01:00 · 2017-04-27 12:01:11 +01:00 · 1d0a629dcc
commit 1d0a629dcc
parent ce99ffe205
82 changed files with 335 additions and 232 deletions
--- a/lib/ansible/modules/cloud/amazon/cloudformation.py
+++ b/lib/ansible/modules/cloud/amazon/cloudformation.py
@ -204,6 +204,7 @@ log:
  sample: ["updating stack"]
 stack_resources:
  description: AWS stack resources and their status. List of dictionaries, one dict per resource.
+  returned: state == present
  type: list
  sample: [
          {
@ -218,7 +219,7 @@ stack_resources:
 stack_outputs:
  type: dict
  description: A key:value dictionary of all the stack outputs currently defined. If there are no stack outputs, it is an empty dictionary.
-  returned: always
+  returned: state == present
  sample: {"MySg": "AnsibleModuleTestYAML-CFTestSg-C8UVS567B6NS"}
 '''  # NOQA

--- a/lib/ansible/modules/cloud/amazon/cloudformation_facts.py
+++ b/lib/ansible/modules/cloud/amazon/cloudformation_facts.py
@ -124,7 +124,7 @@ stack_parameters:
 stack_events:
    description: All stack events for the stack
    returned: only if all_facts or stack_events is true
-    type: list of events
+    type: list
 stack_policy:
    description: Describes the stack policy for the stack
    returned: only if all_facts or stack_policy is true
@ -136,7 +136,7 @@ stack_template:
 stack_resource_list:
    description: Describes stack resources for the stack
    returned: only if all_facts or stack_resourses is true
-    type: list of resources
+    type: list
 stack_resources:
    description: Dictionary of stack resources keyed by the value of each resource 'LogicalResourceId' parameter and corresponding value of each
                 resource 'PhysicalResourceId' parameter
--- a/lib/ansible/modules/cloud/amazon/ec2_ami.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_ami.py
@ -256,7 +256,7 @@ architecture:
 block_device_mapping:
    description: block device mapping associated with image
    returned: when AMI is created or already exists
-    type: a dictionary of block devices
+    type: dict
    sample: {
        "/dev/sda1": {
            "delete_on_termination": true,
@ -329,7 +329,7 @@ state:
 tags:
    description: a dictionary of tags assigned to image
    returned: when AMI is created or already exists
-    type: dictionary of tags
+    type: dict
    sample: {
        "Env": "devel",
        "Name": "nat-server"
--- a/lib/ansible/modules/cloud/amazon/ec2_ami_find.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_ami_find.py
@ -213,7 +213,7 @@ architecture:
 block_device_mapping:
    description: block device mapping associated with image
    returned: when AMI found
-    type: dictionary of block devices
+    type: dict
    sample: "{
        '/dev/xvda': {
            'delete_on_termination': true,
@ -280,7 +280,7 @@ state:
 tags:
    description: tags assigned to image
    returned: when AMI found
-    type: dictionary of tags
+    type: dict
    sample: "{
        'Environment': 'devel',
        'Name': 'test-server01',
--- a/lib/ansible/modules/cloud/amazon/ec2_eni.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_eni.py
@ -190,7 +190,7 @@ RETURN = '''
 interface:
  description: Network interface attributes
  returned: when state != absent
-  type: dictionary
+  type: complex
  contains:
    description:
      description: interface description
--- a/lib/ansible/modules/cloud/amazon/ec2_group_facts.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_group_facts.py
@ -94,6 +94,7 @@ RETURN = '''
 security_groups:
    description: Security groups that match the provided filters. Each element consists of a dict with all the information related to that security group.
    type: list
+    returned: always
    sample:
 '''

--- a/lib/ansible/modules/cloud/amazon/ec2_lc_facts.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_lc_facts.py
@ -83,7 +83,8 @@ EXAMPLES = '''
 RETURN = '''
 block_device_mapping:
    description: Block device mapping for the instances of launch configuration
-    type: list of block devices
+    type: list
+    returned: always
    sample: "[{
        'device_name': '/dev/xvda':,
        'ebs': {
@ -94,58 +95,71 @@ block_device_mapping:
 classic_link_vpc_security_groups:
    description: IDs of one or more security groups for the VPC specified in classic_link_vpc_id
    type: string
+    returned: always
    sample:
 created_time:
    description: The creation date and time for the launch configuration
    type: string
+    returned: always
    sample: "2016-05-27T13:47:44.216000+00:00"
 ebs_optimized:
    description: EBS I/O optimized (true ) or not (false )
    type: bool
+    returned: always
    sample: true,
 image_id:
    description: ID of the Amazon Machine Image (AMI)
    type: string
+    returned: always
    sample: "ami-12345678"
 instance_monitoring:
    description: Launched with detailed monitoring or not
    type: dict
+    returned: always
    sample: "{
        'enabled': true
    }"
 instance_type:
    description: Instance type
    type: string
+    returned: always
    sample: "t2.micro"
 kernel_id:
    description: ID of the kernel associated with the AMI
    type: string
+    returned: always
    sample:
 key_name:
    description: Name of the key pair
    type: string
+    returned: always
    sample: "user_app"
 launch_configuration_arn:
    description: Amazon Resource Name (ARN) of the launch configuration
    type: string
+    returned: always
    sample: "arn:aws:autoscaling:us-east-1:666612345678:launchConfiguration:ba785e3a-dd42-6f02-4585-ea1a2b458b3d:launchConfigurationName/lc-app"
 launch_configuration_name:
    description: Name of the launch configuration
    type: string
+    returned: always
    sample: "lc-app"
 ramdisk_id:
    description: ID of the RAM disk associated with the AMI
    type: string
+    returned: always
    sample:
 security_groups:
    description: Security groups to associated
    type: list
+    returned: always
    sample: "[
        'web'
    ]"
 user_data:
    description: User data available
    type: string
+    returned: always
    sample:
 '''

--- a/lib/ansible/modules/cloud/amazon/ec2_lc_find.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_lc_find.py
@ -83,7 +83,7 @@ user_data:
    description: User data used to start instance
    returned: when Launch Configuration was found
    type: string
-    user_data: "ZXhwb3J0IENMT1VE"
+    sample: "ZXhwb3J0IENMT1VE"
 name:
    description: Name of the AMI
    returned: when Launch Configuration was found
--- a/lib/ansible/modules/cloud/amazon/ec2_snapshot_facts.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_snapshot_facts.py
@ -103,62 +103,76 @@ RETURN = '''
 snapshot_id:
    description: The ID of the snapshot. Each snapshot receives a unique identifier when it is created.
    type: string
+    returned: always
    sample: snap-01234567
 volume_id:
    description: The ID of the volume that was used to create the snapshot.
    type: string
+    returned: always
    sample: vol-01234567
 state:
    description: The snapshot state (completed, pending or error).
    type: string
+    returned: always
    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: string
+    returned: always
    sample:
 start_time:
    description: The time stamp when the snapshot was initiated.
-    type: datetime
-    sample: 2015-02-12T02:14:02+00:00
+    type: string
+    returned: always
+    sample: "2015-02-12T02:14:02+00:00"
 progress:
    description: The progress of the snapshot, as a percentage.
    type: string
-    sample: 100%
+    returned: always
+    sample: "100%"
 owner_id:
    description: The AWS account ID of the EBS snapshot owner.
    type: string
-    sample: 099720109477
+    returned: always
+    sample: "099720109477"
 description:
    description: The description for the snapshot.
    type: string
-    sample: My important backup
+    returned: always
+    sample: "My important backup"
 volume_size:
    description: The size of the volume, in GiB.
-    type: integer
+    type: int
+    returned: always
    sample: 8
 owner_alias:
    description: The AWS account alias (for example, amazon, self) or AWS account ID that owns the snapshot.
    type: string
-    sample: 033440102211
+    returned: always
+    sample: "033440102211"
 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: boolean
-    sample: True
+    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.
    type: string
-    sample: 74c9742a-a1b2-45cb-b3fe-abcdef123456
+    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: string
+    returned: always
    sample: "arn:aws:kms:ap-southeast-2:012345678900:key/74c9742a-a1b2-45cb-b3fe-abcdef123456"

 '''
--- a/lib/ansible/modules/cloud/amazon/ec2_vpc_nacl_facts.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_vpc_nacl_facts.py
@ -71,7 +71,7 @@ RETURN = '''
 nacl:
    description: Returns an array of complex objects as described below.
    returned: success
-    type: list of complex
+    type: complex
    contains:
        nacl_id:
            description: The ID of the Network Access Control List.
--- a/lib/ansible/modules/cloud/amazon/ecs_cluster.py
+++ b/lib/ansible/modules/cloud/amazon/ecs_cluster.py
@ -83,11 +83,13 @@ activeServicesCount:
    type: int
 clusterArn:
    description: the ARN of the cluster just created
-    type: string (ARN)
+    type: string
+    returned: 0 if a new cluster
    sample: arn:aws:ecs:us-west-2:172139249013:cluster/test-cluster-mfshcdok
 clusterName:
    description: name of the cluster just created (should match the input argument)
    type: string
+    returned: always
    sample: test-cluster-mfshcdok
 pendingTasksCount:
    description: how many tasks are waiting to run in this cluster
@ -103,8 +105,9 @@ runningTasksCount:
    type: int
 status:
    description: the status of the new cluster
-    returned: ACTIVE
+    returned: always
    type: string
+    sample: ACTIVE
 '''
 import time

--- a/lib/ansible/modules/cloud/amazon/ecs_ecr.py
+++ b/lib/ansible/modules/cloud/amazon/ecs_ecr.py
@ -104,9 +104,11 @@ RETURN = '''
 state:
    type: string
    description: The asserted state of the repository (present, absent)
+    returned: always
 created:
    type: boolean
    description: If true, the repository was created
+    returned: always
 name:
    type: string
    description: The name of the repository
--- a/lib/ansible/modules/cloud/amazon/ecs_service_facts.py
+++ b/lib/ansible/modules/cloud/amazon/ecs_service_facts.py
@ -71,7 +71,7 @@ RETURN = '''
 services:
    description: When details is false, returns an array of service ARNs, otherwise an array of complex objects as described below.
    returned: success
-    type: list of complex
+    type: complex
    contains:
        clusterArn:
            description: The Amazon Resource Name (ARN) of the of the cluster that hosts the service.
--- a/lib/ansible/modules/cloud/amazon/ecs_taskdefinition.py
+++ b/lib/ansible/modules/cloud/amazon/ecs_taskdefinition.py
@ -111,7 +111,8 @@ EXAMPLES = '''
 RETURN = '''
 taskdefinition:
    description: a reflection of the input parameters
-    type: dict inputs plus revision, status, taskDefinitionArn
+    type: dict
+    returned: always
 '''
 try:
    import boto
--- a/lib/ansible/modules/cloud/amazon/efs.py
+++ b/lib/ansible/modules/cloud/amazon/efs.py
@ -115,33 +115,33 @@ EXAMPLES = '''
 RETURN = '''
 creation_time:
    description: timestamp of creation date
-    returned:
-    type: datetime
-    sample: 2015-11-16 07:30:57-05:00
+    returned: always
+    type: string
+    sample: "2015-11-16 07:30:57-05:00"
 creation_token:
    description: EFS creation token
-    returned:
-    type: UUID
-    sample: console-88609e04-9a0e-4a2e-912c-feaa99509961
+    returned: always
+    type: string
+    sample: "console-88609e04-9a0e-4a2e-912c-feaa99509961"
 file_system_id:
    description: ID of the file system
-    returned:
-    type: unique ID
-    sample: fs-xxxxxxxx
+    returned: always
+    type: string
+    sample: "fs-xxxxxxxx"
 life_cycle_state:
    description: state of the EFS file system
-    returned:
-    type: str
-    sample: creating, available, deleting, deleted
+    returned: always
+    type: string
+    sample: "creating, available, deleting, deleted"
 mount_point:
    description: url of file system
-    returned:
-    type: str
-    sample: .fs-xxxxxxxx.efs.us-west-2.amazonaws.com:/
+    returned: always
+    type: string
+    sample: ".fs-xxxxxxxx.efs.us-west-2.amazonaws.com:/"
 mount_targets:
    description: list of mount targets
-    returned:
-    type: list of dicts
+    returned: always
+    type: list
    sample:
        [
            {
@ -160,22 +160,22 @@ mount_targets:
        ]
 name:
    description: name of the file system
-    returned:
-    type: str
-    sample: my-efs
+    returned: always
+    type: string
+    sample: "my-efs"
 number_of_mount_targets:
    description: the number of targets mounted
-    returned:
+    returned: always
    type: int
    sample: 3
 owner_id:
    description: AWS account ID of EFS owner
-    returned:
-    type: str
-    sample: XXXXXXXXXXXX
+    returned: always
+    type: string
+    sample: "XXXXXXXXXXXX"
 size_in_bytes:
    description: size of the file system in bytes as of a timestamp
-    returned:
+    returned: always
    type: dict
    sample:
        {
@ -184,12 +184,12 @@ size_in_bytes:
        }
 performance_mode:
    description: performance mode of the file system
-    returned:
-    type: str
+    returned: always
+    type: string
    sample: "generalPurpose"
 tags:
    description: tags on the efs instance
-    returned:
+    returned: always
    type: dict
    sample:
        {
--- a/lib/ansible/modules/cloud/amazon/efs_facts.py
+++ b/lib/ansible/modules/cloud/amazon/efs_facts.py
@ -80,33 +80,33 @@ EXAMPLES = '''
 RETURN = '''
 creation_time:
    description: timestamp of creation date
-    returned:
-    type: datetime
-    sample: 2015-11-16 07:30:57-05:00
+    returned: always
+    type: str
+    sample: "2015-11-16 07:30:57-05:00"
 creation_token:
    description: EFS creation token
-    returned:
-    type: UUID
+    returned: always
+    type: str
    sample: console-88609e04-9a0e-4a2e-912c-feaa99509961
 file_system_id:
    description: ID of the file system
-    returned:
-    type: unique ID
+    returned: always
+    type: str
    sample: fs-xxxxxxxx
 life_cycle_state:
    description: state of the EFS file system
-    returned:
+    returned: always
    type: str
    sample: creating, available, deleting, deleted
 mount_point:
    description: url of file system
-    returned:
+    returned: always
    type: str
    sample: .fs-xxxxxxxx.efs.us-west-2.amazonaws.com:/
 mount_targets:
    description: list of mount targets
-    returned:
-    type: list of dicts
+    returned: always
+    type: list
    sample:
        [
            {
@ -125,22 +125,22 @@ mount_targets:
        ]
 name:
    description: name of the file system
-    returned:
+    returned: always
    type: str
    sample: my-efs
 number_of_mount_targets:
    description: the number of targets mounted
-    returned:
+    returned: always
    type: int
    sample: 3
 owner_id:
    description: AWS account ID of EFS owner
-    returned:
+    returned: always
    type: str
    sample: XXXXXXXXXXXX
 size_in_bytes:
    description: size of the file system in bytes as of a timestamp
-    returned:
+    returned: always
    type: dict
    sample:
        {
@ -149,12 +149,12 @@ size_in_bytes:
        }
 performance_mode:
    description: performance mode of the file system
-    returned:
+    returned: always
    type: str
    sample: "generalPurpose"
 tags:
    description: tags on the efs instance
-    returned:
+    returned: always
    type: dict
    sample:
        {
--- a/lib/ansible/modules/cloud/amazon/execute_lambda.py
+++ b/lib/ansible/modules/cloud/amazon/execute_lambda.py
@ -127,10 +127,12 @@ output:
 logs:
    description: The last 4KB of the function logs. Only provided if I(tail_log) is true
    type: string
+    returned: if I(tail_log) == true
 status:
    description: C(StatusCode) of API call exit (200 for synchronous invokes, 202 for async)
    type: int
    sample: 200
+    returned: always
 '''

 import base64
--- a/lib/ansible/modules/cloud/amazon/iam_role.py
+++ b/lib/ansible/modules/cloud/amazon/iam_role.py
@ -92,26 +92,32 @@ RETURN = '''
 path:
    description: the path to the role
    type: string
+    returned: always
    sample: /
 role_name:
    description: the friendly name that identifies the role
    type: string
+    returned: always
    sample: myrole
 role_id:
    description: the stable and unique string identifying the role
    type: string
+    returned: always
    sample: ABCDEFF4EZ4ABCDEFV4ZC
 arn:
    description: the Amazon Resource Name (ARN) specifying the role
    type: string
+    returned: always
    sample: "arn:aws:iam::1234567890:role/mynewrole"
 create_date:
    description: the date and time, in ISO 8601 date-time format, when the role was created
    type: string
+    returned: always
    sample: "2016-08-14T04:36:28+00:00"
 assume_role_policy_document:
    description: the policy that grants an entity permission to assume the role
    type: string
+    returned: always
    sample: {
                'statement': [
                    {
@ -128,6 +134,7 @@ assume_role_policy_document:
 attached_policies:
    description: a list of dicts containing the name and ARN of the managed IAM policies attached to the role
    type: list
+    returned: always
    sample: [
        {
            'policy_arn': 'arn:aws:iam::aws:policy/PowerUserAccess',
--- a/lib/ansible/modules/cloud/amazon/redshift.py
+++ b/lib/ansible/modules/cloud/amazon/redshift.py
@ -155,7 +155,7 @@ RETURN = '''
 cluster:
    description: dictionary containing all the cluster information
    returned: success
-    type: dictionary
+    type: complex
    contains:
        identifier:
            description: Id of the cluster.
--- a/lib/ansible/modules/cloud/amazon/redshift_subnet_group.py
+++ b/lib/ansible/modules/cloud/amazon/redshift_subnet_group.py
@ -77,7 +77,7 @@ RETURN = '''
 group:
    description: dictionary containing all Redshift subnet group information
    returned: success
-    type: dictionary
+    type: complex
    contains:
        name:
            description: name of the Redshift subnet group
--- a/lib/ansible/modules/cloud/amazon/s3_website.py
+++ b/lib/ansible/modules/cloud/amazon/s3_website.py
@ -95,44 +95,59 @@ EXAMPLES = '''

 RETURN = '''
 index_document:
-  suffix:
-    description: suffix that is appended to a request that is for a directory on the website endpoint
-    returned: success
-    type: string
-    sample: index.html
+    description: index document
+    type: complex
+    returned: always
+    contains:
+        suffix:
+            description: suffix that is appended to a request that is for a directory on the website endpoint
+            returned: success
+            type: string
+            sample: index.html
 error_document:
-  key:
-    description:  object key name to use when a 4XX class error occurs
-    returned: when error_document parameter set
-    type: string
-    sample: error.html
+    description: error document
+    type: complex
+    returned: always
+    contains:
+        key:
+            description:  object key name to use when a 4XX class error occurs
+            returned: when error_document parameter set
+            type: string
+            sample: error.html
 redirect_all_requests_to:
-  host_name:
-    description: name of the host where requests will be redirected.
-    returned: when redirect all requests parameter set
-    type: string
-    sample: ansible.com
+    description: where to redirect requests
+    type: complex
+    returned: always
+    contains:
+        host_name:
+            description: name of the host where requests will be redirected.
+            returned: when redirect all requests parameter set
+            type: string
+            sample: ansible.com
 routing_rules:
-  routing_rule:
-    host_name:
-      description: name of the host where requests will be redirected.
-      returned: when host name set as part of redirect rule
-      type: string
-      sample: ansible.com
-    condition:
-      key_prefix_equals:
-        description: object key name prefix when the redirect is applied. For example, to redirect requests for ExamplePage.html, the key prefix will be
+    description: routing rules
+    type: complex
+    returned: always
+    contains:
+        routing_rule:
+            host_name:
+                description: name of the host where requests will be redirected.
+                returned: when host name set as part of redirect rule
+                type: string
+                sample: ansible.com
+        condition:
+            key_prefix_equals:
+            description: object key name prefix when the redirect is applied. For example, to redirect requests for ExamplePage.html, the key prefix will be
                     ExamplePage.html
-        returned: when routing rule present
-        type: string
-        sample: docs/
-    redirect:
-      replace_key_prefix_with:
-        description: object key prefix to use in the redirect request
-        returned: when routing rule present
-        type: string
-        sample: documents/
-
+            returned: when routing rule present
+            type: string
+            sample: docs/
+        redirect:
+            replace_key_prefix_with:
+                description: object key prefix to use in the redirect request
+                returned: when routing rule present
+                type: string
+                sample: documents/
 '''

 import time
--- a/lib/ansible/modules/cloud/amazon/sns_topic.py
+++ b/lib/ansible/modules/cloud/amazon/sns_topic.py
@ -105,11 +105,13 @@ RETURN = '''
 sns_arn:
    description: The ARN of the topic you are modifying
    type: string
+    returned: always
    sample: "arn:aws:sns:us-east-1:123456789012:my_topic_name"

 sns_topic:
    description: Dict of sns topic details
    type: dict
+    returned: always
    sample:
      name: sns-topic-name
      state: present
--- a/lib/ansible/modules/cloud/amazon/sqs_queue.py
+++ b/lib/ansible/modules/cloud/amazon/sqs_queue.py
@ -89,34 +89,42 @@ extends_documentation_fragment:
 RETURN = '''
 default_visibility_timeout:
    description: The default visibility timeout in seconds.
+    type: int
    returned: always
    sample: 30
 delivery_delay:
    description: The delivery delay in seconds.
+    type: int
    returned: always
    sample: 0
 maximum_message_size:
    description: The maximum message size in bytes.
+    type: int
    returned: always
    sample: 262144
 message_retention_period:
    description: The message retention period in seconds.
+    type: int
    returned: always
    sample: 345600
 name:
    description: Name of the SQS Queue
+    type: string
    returned: always
    sample: "queuename-987d2de0"
 queue_arn:
    description: The queue's Amazon resource name (ARN).
+    type: string
    returned: on successful creation or update of the queue
    sample: 'arn:aws:sqs:us-east-1:199999999999:queuename-987d2de0'
 receive_message_wait_time:
    description: The receive message wait time in seconds.
+    type: int
    returned: always
    sample: 0
 region:
    description: Region that the queue was created within
+    type: string
    returned: always
    sample: 'us-east-1'
 '''