Yet more Sanity test "required" Amazon module cleanup (#65554)

* More 'required' cleanup on AWS modules.

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

@@ -33,7 +33,6 @@ options:
       - I(state=enabled) is equivalet to I(state=present).
       - I(state=disabled) is equivalet to I(state=absent).
     type: str
-    required: true
     choices: ['present', 'absent', 'enabled', 'disabled']
     default: present
   name:
@@ -41,7 +40,6 @@ options:
       - Name for the CloudTrail.
       - Names are unique per-region unless the CloudTrail is a multi-region trail, in which case it is unique per-account.
     type: str
-    required: true
     default: default
   enable_logging:
     description:

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

@@ -20,8 +20,9 @@ version_added: "0.9"
 options:
   key_name:
     description:
-      - key pair to use on the instance. The SSH key must exist on AWS in order to use this argument. If you want to generate keys from Ansible,
+      - Key pair to use on the instance.
-        take a look at `ec2_key` module.
+      - The SSH key must already exist in AWS in order to use this argument.
+      - Keys can be created / deleted using the M(ec2_key) module.
     aliases: ['keypair']
     type: str
   id:
@@ -36,19 +37,13 @@ options:
       - Security group (or list of groups) to use with the instance.
     aliases: [ 'groups' ]
     type: list
+    elements: str
   group_id:
     version_added: "1.1"
     description:
       - Security group id (or list of ids) to use with the instance.
     type: list
-  region:
+    elements: str
-    version_added: "1.2"
-    description:
-      - The AWS region to use.  Must be specified if ec2_url is not used.
-      - If not specified then the value of the C(AWS_REGION) or C(EC2_REGION) environment variable, if any, is used.
-      - See U(https://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region).
-    aliases: [ 'aws_region', 'ec2_region' ]
-    type: str
   zone:
     version_added: "1.2"
     description:
@@ -58,13 +53,13 @@ options:
   instance_type:
     description:
       - Instance type to use for the instance, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html).
-    required: true
+      - Required when creating a new instance.
     type: str
     aliases: ['type']
   tenancy:
     version_added: "1.9"
     description:
-      - An instance with a tenancy of "dedicated" runs on single-tenant hardware and can only be launched into a VPC.
+      - An instance with a tenancy of C(dedicated) runs on single-tenant hardware and can only be launched into a VPC.
       - Note that to use dedicated tenancy you MUST specify a I(vpc_subnet_id) as well.
       - Dedicated tenancy is not available for EC2 "micro" instances.
     default: default
@@ -79,29 +74,30 @@ options:
   spot_type:
     version_added: "2.0"
     description:
-      - Type of spot request; one of "one-time" or "persistent". Defaults to "one-time" if not supplied.
+      - The type of spot request.
+      - After being interrupted a C(persistent) spot instance will be started once there is capacity to fill the request again.
     default: "one-time"
     choices: [ "one-time", "persistent" ]
     type: str
   image:
     description:
        - I(ami) ID to use for the instance.
-    required: true
+       - Required when I(state=present).
     type: str
   kernel:
     description:
-      - Kernel I(eki) to use for the instance.
+      - Kernel eki to use for the instance.
     type: str
   ramdisk:
     description:
-      - Ramdisk I(eri) to use for the instance.
+      - Ramdisk eri to use for the instance.
     type: str
   wait:
     description:
       - Wait for the instance to reach its desired state before returning.
-      - Does not wait for SSH, see 'wait_for_connection' example for details.
+      - Does not wait for SSH, see the 'wait_for_connection' example for details.
     type: bool
-    default: 'no'
+    default: false
   wait_timeout:
     description:
       - How long before wait gives up, in seconds.
@@ -123,7 +119,7 @@ options:
     description:
       - Enable detailed monitoring (CloudWatch) for instance.
     type: bool
-    default: 'no'
+    default: false
   user_data:
     version_added: "0.9"
     description:
@@ -165,18 +161,19 @@ options:
       - "list of instance ids, currently used for states: absent, running, stopped"
     aliases: ['instance_id']
     type: list
+    elements: str
   source_dest_check:
     version_added: "1.6"
     description:
       - Enable or Disable the Source/Destination checks (for NAT instances and Virtual Routers).
-        When initially creating an instance the EC2 API defaults this to True.
+        When initially creating an instance the EC2 API defaults this to C(True).
     type: bool
   termination_protection:
     version_added: "2.0"
     description:
       - Enable or Disable the Termination Protection.
     type: bool
-    default: 'no'
+    default: false
   instance_initiated_shutdown_behavior:
     version_added: "2.2"
     description:
@@ -189,24 +186,63 @@ options:
     version_added: "1.3"
     description:
       - Create, terminate, start, stop or restart instances. The state 'restarted' was added in Ansible 2.2.
-      - When 'absent', I(instance_ids) is required.
+      - When I(state=absent), I(instance_ids) is required.
-      - When 'running', 'stopped' and 'restarted', I(instance_ids) or I(instance_tags) is required.
+      - When I(state=running), I(state=stopped) or I(state=restarted) then either I(instance_ids) or I(instance_tags) is required.
     default: 'present'
     choices: ['absent', 'present', 'restarted', 'running', 'stopped']
     type: str
   volumes:
     version_added: "1.5"
     description:
-      - a list of hash/dictionaries of volumes to add to the new instance; '[{"key":"value", "key":"value"}]'; keys allowed
+      - A list of hash/dictionaries of volumes to add to the new instance.
-        are - device_name (str; required), delete_on_termination (bool; False), ephemeral (str),
-        encrypted (bool; False), snapshot (str), volume_type (str), volume_size (int, GiB), iops (int) - iops must be set when
-        volume_type='io1', ephemeral and snapshot are mutually exclusive.
     type: list
+    elements: dict
+    suboptions:
+      device_name:
+        type: str
+        required: true
+        description:
+          - A name for the device (For example C(/dev/sda)).
+      delete_on_termination:
+        type: bool
+        default: false
+        description:
+          - Whether the volume should be automatically deleted when the instance is terminated.
+      ephemeral:
+        type: str
+        description:
+          - Whether the volume should be ephemeral.
+          - Data on ephemeral volumes is lost when the instance is stopped.
+          - Mutually exclusive with the I(snapshot) parameter.
+      encrypted:
+        type: bool
+        default: false
+        description:
+          - Whether the volume should be encrypted using the 'aws/ebs' KMS CMK.
+      snapshot:
+        type: str
+        description:
+          - The ID of an EBS snapshot to copy when creating the volume.
+          - Mutually exclusive with the I(ephemeral) parameter.
+      volume_type:
+        type: str
+        description:
+          - The type of volume to create.
+          - See U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html) for more information on the available volume types.
+      volume_size:
+        type: int
+        description:
+          - The size of the volume (in GiB).
+      iops:
+        type: int
+        description:
+          - The number of IOPS per second to provision for the volume.
+          - Required when I(volume_type=io1).
   ebs_optimized:
     version_added: "1.6"
     description:
-      - whether instance is using optimized EBS volumes, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html).
+      - Whether instance is using optimized EBS volumes, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html).
-    default: 'no'
+    default: false
     type: bool
   exact_count:
     version_added: "1.5"
@@ -217,28 +253,31 @@ options:
   count_tag:
     version_added: "1.5"
     description:
-      - Used with 'exact_count' to determine how many nodes based on a specific tag criteria should be running.
+      - Used with I(exact_count) to determine how many nodes based on a specific tag criteria should be running.
         This can be expressed in multiple ways and is shown in the EXAMPLES section.  For instance, one can request 25 servers
-        that are tagged with "class=webserver". The specified tag must already exist or be passed in as the 'instance_tags' option.
+        that are tagged with "class=webserver". The specified tag must already exist or be passed in as the I(instance_tags) option.
     type: raw
   network_interfaces:
     version_added: "2.0"
     description:
       - A list of existing network interfaces to attach to the instance at launch. When specifying existing network interfaces,
-        none of the assign_public_ip, private_ip, vpc_subnet_id, group, or group_id parameters may be used. (Those parameters are
+        none of the I(assign_public_ip), I(private_ip), I(vpc_subnet_id), I(group), or I(group_id) parameters may be used. (Those parameters are
         for creating a new network interface at launch.)
     aliases: ['network_interface']
     type: list
+    elements: str
   spot_launch_group:
     version_added: "2.1"
     description:
-      - Launch group for spot request, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-spot-instances-work.html#spot-launch-group).
+      - Launch group for spot requests, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-spot-instances-work.html#spot-launch-group).
     type: str
 author:
     - "Tim Gerla (@tgerla)"
     - "Lester Wade (@lwade)"
     - "Seth Vidal (@skvidal)"
-extends_documentation_fragment: aws
+extends_documentation_fragment:
+    - aws
+    - ec2
 '''
 
 EXAMPLES = '''

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

@@ -25,7 +25,6 @@ options:
     description:
       - Create or delete Lifecycle Hook.
       - When I(state=present) updates existing hook or creates a new hook if not found.
-    required: false
     choices: ['present', 'absent']
     default: present
     type: str
@@ -42,13 +41,12 @@ options:
   transition:
     description:
       - The instance state to which you want to attach the lifecycle hook.
-    required: true
+      - Required when I(state=present).
     choices: ['autoscaling:EC2_INSTANCE_TERMINATING', 'autoscaling:EC2_INSTANCE_LAUNCHING']
     type: str
   role_arn:
     description:
       - The ARN of the IAM role that allows the Auto Scaling group to publish to the specified notification target.
-    required: false
     type: str
   notification_target_arn:
     description:
@@ -56,26 +54,22 @@ options:
         instance is in the transition state for the lifecycle hook.
       - This target can be either an SQS queue or an SNS topic.
       - If you specify an empty string, this overrides the current ARN.
-    required: false
     type: str
   notification_meta_data:
     description:
       - Contains additional information that you want to include any time Auto Scaling sends a message to the notification target.
-    required: false
     type: str
   heartbeat_timeout:
     description:
       - The amount of time, in seconds, that can elapse before the lifecycle hook times out.
         When the lifecycle hook times out, Auto Scaling performs the default action.
         You can prevent the lifecycle hook from timing out by calling RecordLifecycleActionHeartbeat.
-      - By default amazon will use 3600 (1 hour)
+      - By default Amazon AWS will use 3600 (1 hour)
-    required: false
     type: int
   default_result:
     description:
       - Defines the action the Auto Scaling group should take when the lifecycle hook timeout
-        elapses or if an unexpected failure occurs. This parameter can be either CONTINUE or ABANDON.
+        elapses or if an unexpected failure occurs.
-    required: false
     choices: ['ABANDON', 'CONTINUE']
     default: ABANDON
     type: str

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

@@ -47,7 +47,7 @@ options:
   instance_type:
     description:
       - Instance type to use for the instance.
-    required: true
+      - Required when creating a new Launch Configuration.
     type: str
   image_id:
     description:
@@ -65,11 +65,58 @@ options:
     elements: str
   volumes:
     description:
-      - A list of volume dicts, each containing device name and optionally ephemeral id or snapshot id. Size and type (and number of iops for io
+      - A list dictionaries defining the volumes to create.
-        device type) must be specified for a new volume or a root volume, and may be passed for a snapshot volume. For any volume, a volume size less
+      - For any volume, a volume size less than 1 will be interpreted as a request not to create the volume.
-        than 1 will be interpreted as a request not to create the volume.
     type: list
     elements: dict
+    suboptions:
+      device_name:
+        type: str
+        description:
+          - The name for the volume (For example C(/dev/sda)).
+        required: true
+      no_device:
+        type: bool
+        description:
+          - When I(no_device=true) the device will not be created.
+      snapshot:
+        type: str
+        description:
+          - The ID of an EBS snapshot to copy when creating the volume.
+          - Mutually exclusive with the I(ephemeral) parameter.
+      ephemeral:
+        type: str
+        description:
+          - Whether the volume should be ephemeral.
+          - Data on ephemeral volumes is lost when the instance is stopped.
+          - Mutually exclusive with the I(snapshot) parameter.
+      volume_size:
+        type: int
+        description:
+          - The size of the volume (in GiB).
+          - Required unless one of I(ephemeral), I(snapshot) or I(no_device) is set.
+      volume_type:
+        type: str
+        description:
+          - The type of volume to create.
+          - See
+            U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html) for more information on the available volume types.
+      delete_on_termination:
+        type: bool
+        default: false
+        description:
+          - Whether the volume should be automatically deleted when the instance
+            is terminated.
+      iops:
+        type: int
+        description:
+          - The number of IOPS per second to provision for the volume.
+          - Required when I(volume_type=io1).
+      encrypted:
+        type: bool
+        default: false
+        description:
+          - Whether the volume should be encrypted using the 'aws/ebs' KMS CMK.
   user_data:
     description:
       - Opaque blob of data which is made available to the ec2 instance. Mutually exclusive with I(user_data_path).

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

@@ -30,7 +30,6 @@ options:
   state:
     description:
       - Create or delete placement group.
-    required: false
     default: present
     choices: [ 'present', 'absent' ]
     type: str
@@ -39,7 +38,6 @@ options:
       - Placement group strategy. Cluster will cluster instances into a
         low-latency group in a single Availability Zone, while Spread spreads
         instances across underlying hardware.
-    required: false
     default: cluster
     choices: [ 'cluster', 'spread' ]
     type: str

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

@@ -24,31 +24,32 @@ options:
   cross_zone_load_balancing:
     description:
       - Indicates whether cross-zone load balancing is enabled.
-    required: false
+    default: false
-    default: no
     type: bool
   deletion_protection:
     description:
       - Indicates whether deletion protection for the ELB is enabled.
-    required: false
+    default: false
-    default: no
     type: bool
   listeners:
     description:
       - A list of dicts containing listeners to attach to the ELB. See examples for detail of the dict required. Note that listener keys
         are CamelCased.
-    required: false
     type: list
+    elements: dict
     suboptions:
         Port:
             description: The port on which the load balancer is listening.
             type: int
+            required: true
         Protocol:
             description: The protocol for connections from clients to the load balancer.
             type: str
+            required: true
         Certificates:
             description: The SSL server certificate.
             type: list
+            elements: dict
             suboptions:
                 CertificateArn:
                     description: The Amazon Resource Name (ARN) of the certificate.
@@ -58,7 +59,9 @@ options:
             type: str
         DefaultActions:
             description: The default actions for the listener.
+            required: true
             type: list
+            elements: dict
             suboptions:
                 Type:
                     description: The type of action.
@@ -74,46 +77,44 @@ options:
     type: str
   purge_listeners:
     description:
-      - If yes, existing listeners will be purged from the ELB to match exactly what is defined by I(listeners) parameter. If the I(listeners) parameter is
+      - If I(purge_listeners=true), existing listeners will be purged from the ELB to match exactly what is defined by I(listeners) parameter.
-        not set then listeners will not be modified
+      - If the I(listeners) parameter is not set then listeners will not be modified.
-    default: yes
+    default: true
     type: bool
   purge_tags:
     description:
-      - If yes, existing tags will be purged from the resource to match exactly what is defined by I(tags) parameter. If the I(tags) parameter is not set then
+      - If I(purge_tags=true), existing tags will be purged from the resource to match exactly what is defined by I(tags) parameter.
-        tags will not be modified.
+      - If the I(tags) parameter is not set then tags will not be modified.
-    required: false
+    default: true
-    default: yes
     type: bool
   subnet_mappings:
     description:
       - A list of dicts containing the IDs of the subnets to attach to the load balancer. You can also specify the allocation ID of an Elastic IP
-        to attach to the load balancer. You can specify one Elastic IP address per subnet. This parameter is mutually exclusive with I(subnets)
+        to attach to the load balancer. You can specify one Elastic IP address per subnet.
-    required: false
+      - This parameter is mutually exclusive with I(subnets).
     type: list
+    elements: dict
   subnets:
     description:
       - A list of the IDs of the subnets to attach to the load balancer. You can specify only one subnet per Availability Zone. You must specify subnets from
-        at least two Availability Zones. Required if state=present. This parameter is mutually exclusive with I(subnet_mappings)
+        at least two Availability Zones.
-    required: false
+      - Required when I(state=present).
+      - This parameter is mutually exclusive with I(subnet_mappings).
     type: list
   scheme:
     description:
       - Internet-facing or internal load balancer. An ELB scheme can not be modified after creation.
-    required: false
     default: internet-facing
     choices: [ 'internet-facing', 'internal' ]
     type: str
   state:
     description:
       - Create or destroy the load balancer.
-    required: true
     choices: [ 'present', 'absent' ]
     type: str
   tags:
     description:
       - A dictionary of one or more tags to assign to the load balancer.
-    required: false
     type: dict
   wait:
     description:

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

@@ -21,21 +21,21 @@ version_added: "2.0"
 options:
   iam_type:
     description:
-      - Type of IAM resource
+      - Type of IAM resource.
     choices: ["user", "group", "role"]
     type: str
   name:
     description:
-      - Name of IAM resource to create or identify
+      - Name of IAM resource to create or identify.
     required: true
     type: str
   new_name:
     description:
-      - When state is update, will replace name with new_name on IAM resource
+      - When I(state=update), will replace I(name) with I(new_name) on IAM resource.
     type: str
   new_path:
     description:
-      - When state is update, will replace the path with new_path on the IAM resource
+      - When I(state=update), will replace the path with new_path on the IAM resource.
     type: str
   state:
     description:
@@ -45,18 +45,20 @@ options:
     type: str
   path:
     description:
-      - When creating or updating, specify the desired path of the resource. If state is present,
+      - When creating or updating, specify the desired path of the resource.
-        it will replace the current path to match what is passed in when they do not match.
+      - If I(state=present), it will replace the current path to match what is passed in when they do not match.
     default: "/"
     type: str
   trust_policy:
     description:
-      - The inline (JSON or YAML) trust policy document that grants an entity permission to assume the role. Mutually exclusive with C(trust_policy_filepath).
+      - The inline (JSON or YAML) trust policy document that grants an entity permission to assume the role.
+      - Mutually exclusive with I(trust_policy_filepath).
     version_added: "2.2"
     type: dict
   trust_policy_filepath:
     description:
-      - The path to the trust policy document that grants an entity permission to assume the role. Mutually exclusive with C(trust_policy).
+      - The path to the trust policy document that grants an entity permission to assume the role.
+      - Mutually exclusive with I(trust_policy).
     version_added: "2.2"
     type: str
   access_key_state:
@@ -66,26 +68,29 @@ options:
     type: str
   key_count:
     description:
-      - When access_key_state is create it will ensure this quantity of keys are present. Defaults to 1.
+      - When I(access_key_state=create) it will ensure this quantity of keys are present.
     default: 1
     type: int
   access_key_ids:
     description:
-      - A list of the keys that you want impacted by the access_key_state parameter.
+      - A list of the keys that you want affected by the I(access_key_state) parameter.
     type: list
   groups:
     description:
-      - A list of groups the user should belong to. When update, will gracefully remove groups not listed.
+      - A list of groups the user should belong to. When I(state=update), will gracefully remove groups not listed.
     type: list
   password:
     description:
-      - When type is user and state is present, define the users login password. Also works with update. Note that always returns changed.
+      - When I(type=user) and either I(state=present) or I(state=update), define the users login password.
+      - Note that this will always return 'changed'.
     type: str
   update_password:
     default: always
     choices: ['always', 'on_create']
     description:
-     - C(always) will update passwords if they differ.  C(on_create) will only set the password for newly created users.
+      - When to update user passwords.
+      - I(update_password=always) will ensure the password is set to I(password).
+      - I(update_password=on_create) will only set the password for newly created users.
     type: str
 notes:
   - 'Currently boto does not support the removal of Managed Policies, the module will error out if your

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

@@ -27,7 +27,7 @@ DOCUMENTATION = '''
 module: iam_cert
 short_description: Manage server certificates for use on ELBs and CloudFront
 description:
-     - Allows for the management of server certificates
+     - Allows for the management of server certificates.
 version_added: "2.0"
 options:
   name:
@@ -43,12 +43,12 @@ options:
   new_path:
     description:
       - When state is present, this will update the path of the cert.
-      - The cert, key and cert_chain parameters will be ignored if this is defined.
+      - The I(cert), I(key) and I(cert_chain) parameters will be ignored if this is defined.
     type: str
   state:
     description:
-      - Whether to create(or update) or delete certificate.
+      - Whether to create(or update) or delete the certificate.
-      - If new_path or new_name is defined, specifying present will attempt to make an update these.
+      - If I(new_path) or I(new_name) is defined, specifying present will attempt to make an update these.
     required: true
     choices: [ "present", "absent" ]
     type: str
@@ -59,7 +59,7 @@ options:
     type: str
   cert_chain:
     description:
-      - The path to, or content of the CA certificate chain in PEM encoded format.
+      - The path to, or content of, the CA certificate chain in PEM encoded format.
         As of 2.4 content is accepted. If the parameter is not a file, it is assumed to be content.
     type: str
   cert:
@@ -75,7 +75,7 @@ options:
   dup_ok:
     description:
       - By default the module will not upload a certificate that is already uploaded into AWS.
-        If set to True, it will upload the certificate as long as the name is unique.
+      - If I(dup_ok=True), it will upload the certificate as long as the name is unique.
     default: False
     type: bool
 

test/sanity/ignore.txt

@@ -491,12 +491,7 @@ lib/ansible/modules/cloud/alicloud/ali_instance.py validate-modules:parameter-ty
 lib/ansible/modules/cloud/alicloud/ali_instance_info.py validate-modules:doc-missing-type
 lib/ansible/modules/cloud/alicloud/ali_instance_info.py validate-modules:doc-required-mismatch
 lib/ansible/modules/cloud/alicloud/ali_instance_info.py validate-modules:parameter-type-not-in-doc
-lib/ansible/modules/cloud/amazon/cloudtrail.py validate-modules:doc-required-mismatch
-lib/ansible/modules/cloud/amazon/ec2.py validate-modules:doc-required-mismatch
-lib/ansible/modules/cloud/amazon/ec2_asg_lifecycle_hook.py validate-modules:doc-required-mismatch
-lib/ansible/modules/cloud/amazon/ec2_lc.py validate-modules:doc-required-mismatch
 lib/ansible/modules/cloud/amazon/ec2_placement_group.py validate-modules:doc-required-mismatch
-lib/ansible/modules/cloud/amazon/elb_network_lb.py validate-modules:doc-required-mismatch
 lib/ansible/modules/cloud/amazon/iam.py validate-modules:doc-required-mismatch
 lib/ansible/modules/cloud/amazon/iam_cert.py validate-modules:doc-required-mismatch
 lib/ansible/modules/cloud/amazon/iam_policy.py validate-modules:doc-required-mismatch