diff --git a/lib/ansible/modules/cloud/amazon/cloudtrail.py b/lib/ansible/modules/cloud/amazon/cloudtrail.py index 0954c3387fc..8df9ea08d36 100644 --- a/lib/ansible/modules/cloud/amazon/cloudtrail.py +++ b/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: diff --git a/lib/ansible/modules/cloud/amazon/ec2.py b/lib/ansible/modules/cloud/amazon/ec2.py index c4b29d9573e..8d0fe39dbcb 100644 --- a/lib/ansible/modules/cloud/amazon/ec2.py +++ b/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, - take a look at `ec2_key` module. + - Key pair to use on the instance. + - 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: - 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 + elements: 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 'running', 'stopped' and 'restarted', I(instance_ids) or I(instance_tags) is required. + - When I(state=absent), I(instance_ids) 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 - 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. + - A list of hash/dictionaries of volumes to add to the new instance. 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). - default: 'no' + - Whether instance is using optimized EBS volumes, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html). + 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 = ''' diff --git a/lib/ansible/modules/cloud/amazon/ec2_asg_lifecycle_hook.py b/lib/ansible/modules/cloud/amazon/ec2_asg_lifecycle_hook.py index 61a802ee550..52825e1435c 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_asg_lifecycle_hook.py +++ b/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) - required: false + - By default Amazon AWS will use 3600 (1 hour) 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. - required: false + elapses or if an unexpected failure occurs. choices: ['ABANDON', 'CONTINUE'] default: ABANDON type: str diff --git a/lib/ansible/modules/cloud/amazon/ec2_lc.py b/lib/ansible/modules/cloud/amazon/ec2_lc.py index 086412db8d3..ea96c02b1b6 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_lc.py +++ b/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 - 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 - than 1 will be interpreted as a request not to create the volume. + - A list dictionaries defining the volumes to create. + - For any volume, a volume size less 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). diff --git a/lib/ansible/modules/cloud/amazon/ec2_placement_group.py b/lib/ansible/modules/cloud/amazon/ec2_placement_group.py index 11dfb3c01c4..31e62280600 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_placement_group.py +++ b/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 diff --git a/lib/ansible/modules/cloud/amazon/elb_network_lb.py b/lib/ansible/modules/cloud/amazon/elb_network_lb.py index 2104081bacd..202ac7e597c 100644 --- a/lib/ansible/modules/cloud/amazon/elb_network_lb.py +++ b/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: no + default: false type: bool deletion_protection: description: - Indicates whether deletion protection for the ELB is enabled. - required: false - default: no + default: false 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 - not set then listeners will not be modified - default: yes + - If I(purge_listeners=true), existing listeners will be purged from the ELB to match exactly what is defined by I(listeners) parameter. + - If the I(listeners) parameter is not set then listeners will not be modified. + 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 - tags will not be modified. - required: false - default: yes + - If I(purge_tags=true), 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 tags will not be modified. + default: true 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) - required: false + to attach to the load balancer. You can specify one Elastic IP address per subnet. + - 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) - required: false + at least two Availability Zones. + - 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: diff --git a/lib/ansible/modules/cloud/amazon/iam.py b/lib/ansible/modules/cloud/amazon/iam.py index e05e3885458..9f375046514 100644 --- a/lib/ansible/modules/cloud/amazon/iam.py +++ b/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, - it will replace the current path to match what is passed in when they do not match. + - When creating or updating, specify the desired path of the resource. + - 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 diff --git a/lib/ansible/modules/cloud/amazon/iam_cert.py b/lib/ansible/modules/cloud/amazon/iam_cert.py index dc55cec6e68..ced5f9d1805 100644 --- a/lib/ansible/modules/cloud/amazon/iam_cert.py +++ b/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. - - If new_path or new_name is defined, specifying present will attempt to make an update these. + - Whether to create(or update) or delete the certificate. + - 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 diff --git a/test/sanity/ignore.txt b/test/sanity/ignore.txt index 00af922fc46..b4798ed16a8 100644 --- a/test/sanity/ignore.txt +++ b/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