From 2d81f29ba56ff7ca88932fa68b1a92839e1195e1 Mon Sep 17 00:00:00 2001 From: Mark Chappell Date: Sat, 5 Dec 2020 18:43:03 +0100 Subject: [PATCH 1/4] Sanity - Ensure defaults documentation matches arg_spec --- plugins/modules/aws_s3.py | 1 + plugins/modules/ec2.py | 2 +- plugins/modules/ec2_elb_lb.py | 2 +- plugins/modules/ec2_vpc_dhcp_option_info.py | 1 + plugins/modules/s3_bucket.py | 1 + 5 files changed, 5 insertions(+), 2 deletions(-) diff --git a/plugins/modules/aws_s3.py b/plugins/modules/aws_s3.py index b6970db15d2..8447d8687d7 100644 --- a/plugins/modules/aws_s3.py +++ b/plugins/modules/aws_s3.py @@ -149,6 +149,7 @@ GetObject permission but no other permissions. In this case using the option mode: get will fail without specifying I(ignore_nonexistent_bucket=true)." type: bool + default: false encryption_kms_key_id: description: - KMS key id to use when encrypting objects using I(encrypting=aws:kms). Ignored if I(encryption) is not C(aws:kms) diff --git a/plugins/modules/ec2.py b/plugins/modules/ec2.py index d29488b21b5..c02b846fac5 100644 --- a/plugins/modules/ec2.py +++ b/plugins/modules/ec2.py @@ -156,8 +156,8 @@ termination_protection: description: - Enable or Disable the Termination Protection. + - Defaults to C(False) type: bool - default: false instance_initiated_shutdown_behavior: description: - Set whether AWS will Stop or Terminate an instance on shutdown. This parameter is ignored when using instance-store. diff --git a/plugins/modules/ec2_elb_lb.py b/plugins/modules/ec2_elb_lb.py index 95bef240979..45980d153a4 100644 --- a/plugins/modules/ec2_elb_lb.py +++ b/plugins/modules/ec2_elb_lb.py @@ -110,8 +110,8 @@ cross_az_load_balancing: description: - Distribute load across all configured Availability Zones + - Defaults to C(false). type: bool - default: no stickiness: description: - An associative array of stickiness policy settings. Policy will be applied to all listeners ( see example ) diff --git a/plugins/modules/ec2_vpc_dhcp_option_info.py b/plugins/modules/ec2_vpc_dhcp_option_info.py index c06c395b5e4..0c0fab9903f 100644 --- a/plugins/modules/ec2_vpc_dhcp_option_info.py +++ b/plugins/modules/ec2_vpc_dhcp_option_info.py @@ -34,6 +34,7 @@ Options. aliases: ['DryRun'] type: bool + default: false extends_documentation_fragment: - amazon.aws.aws - amazon.aws.ec2 diff --git a/plugins/modules/s3_bucket.py b/plugins/modules/s3_bucket.py index f04a6fb4a18..fa250f2383c 100644 --- a/plugins/modules/s3_bucket.py +++ b/plugins/modules/s3_bucket.py @@ -54,6 +54,7 @@ - Enable API compatibility with Ceph. It takes into account the S3 API subset working with Ceph in order to provide the same module behaviour where possible. type: bool + default: false requester_pays: description: - With Requester Pays buckets, the requester instead of the bucket owner pays the cost From 5d8525b83909799bf9fd123ca71e6a43683ac9d7 Mon Sep 17 00:00:00 2001 From: Mark Chappell Date: Sat, 5 Dec 2020 19:58:54 +0100 Subject: [PATCH 2/4] Docs cleanup --- plugins/modules/aws_s3.py | 18 ++++---- plugins/modules/ec2.py | 11 +++-- plugins/modules/ec2_elb_lb.py | 46 ++++++++++----------- plugins/modules/ec2_vpc_dhcp_option_info.py | 2 +- plugins/modules/s3_bucket.py | 40 +++++++++--------- 5 files changed, 61 insertions(+), 56 deletions(-) diff --git a/plugins/modules/aws_s3.py b/plugins/modules/aws_s3.py index 8447d8687d7..3ee2957319a 100644 --- a/plugins/modules/aws_s3.py +++ b/plugins/modules/aws_s3.py @@ -46,7 +46,7 @@ type: int headers: description: - - Custom headers for PUT operation, as a dictionary of 'key=value' and 'key=value,key=value'. + - Custom headers for PUT operation, as a dictionary of C(key=value) and C(key=value,key=value). type: dict marker: description: @@ -59,12 +59,12 @@ type: int metadata: description: - - Metadata for PUT operation, as a dictionary of 'key=value' and 'key=value,key=value'. + - Metadata for PUT operation, as a dictionary of C(key=value) and C(key=value,key=value). type: dict mode: description: - - Switches the module behaviour between put (upload), get (download), geturl (return download url, Ansible 1.3+), - getstr (download object as string (1.3+)), list (list keys, Ansible 2.0+), create (bucket), delete (bucket), + - Switches the module behaviour between C(put) (upload), C(get) (download), C(geturl) (return download url, Ansible 1.3+), + C(getstr) (download object as string (1.3+)), C(list) (list keys, Ansible 2.0+), C(create) (bucket), C(delete) (bucket), and delobj (delete object, Ansible 2.0+). required: true choices: ['get', 'put', 'delete', 'create', 'geturl', 'getstr', 'delobj', 'list'] @@ -94,10 +94,12 @@ overwrite: description: - Force overwrite either locally on the filesystem or remotely with the object/key. Used with PUT and GET operations. - Boolean or one of [always, never, different], true is equal to 'always' and false is equal to 'never', new in 2.0. - When this is set to 'different', the md5 sum of the local file is compared with the 'ETag' of the object/key in S3. + - Must be a Boolean, C(always), C(never) or C(different). + - C(true) is the same as C(always). + - C(false) is equal to C(never) + - When this is set to C(different) the MD5 sum of the local file is compared with the 'ETag' of the object/key in S3. The ETag may or may not be an MD5 digest of the object data. See the ETag response header here - U(https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html) + U(https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html). default: 'always' aliases: ['force'] type: str @@ -152,7 +154,7 @@ default: false encryption_kms_key_id: description: - - KMS key id to use when encrypting objects using I(encrypting=aws:kms). Ignored if I(encryption) is not C(aws:kms) + - KMS key id to use when encrypting objects using I(encrypting=aws:kms). Ignored if I(encryption) is not C(aws:kms). type: str requirements: [ "boto3", "botocore" ] author: diff --git a/plugins/modules/ec2.py b/plugins/modules/ec2.py index c02b846fac5..7d512bac7a7 100644 --- a/plugins/modules/ec2.py +++ b/plugins/modules/ec2.py @@ -111,7 +111,7 @@ type: int monitoring: description: - - Enable detailed monitoring (CloudWatch) for instance. + - Enable detailed monitoring (CloudWatch for instance). type: bool default: false user_data: @@ -120,7 +120,10 @@ type: str instance_tags: description: - - A hash/dictionary of tags to add to the new instance or for starting/stopping instance by tag; '{"key":"value"}' and '{"key":"value","key":"value"}'. + - > + A hash/dictionary of tags to add to the new instance or for + instances to start/stop by tag. For example C({"key":"value"}) or + C({"key":"value","key2":"value2"}). type: dict placement_group: description: @@ -128,7 +131,7 @@ type: str vpc_subnet_id: description: - - the subnet ID in which to launch the instance (VPC). + - The subnet ID in which to launch the instance (VPC). type: str assign_public_ip: description: @@ -233,7 +236,7 @@ description: - 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 I(instance_tags) option. + that are tagged with C(class=webserver). The specified tag must already exist or be passed in as the I(instance_tags) option. type: raw network_interfaces: description: diff --git a/plugins/modules/ec2_elb_lb.py b/plugins/modules/ec2_elb_lb.py index 45980d153a4..a1e732e414e 100644 --- a/plugins/modules/ec2_elb_lb.py +++ b/plugins/modules/ec2_elb_lb.py @@ -19,62 +19,62 @@ options: state: description: - - Create or destroy the ELB + - Create or destroy the ELB. type: str choices: [ absent, present ] required: true name: description: - - The name of the ELB + - The name of the ELB. type: str required: true listeners: description: - - List of ports/protocols for this ELB to listen on (see example) + - List of ports/protocols for this ELB to listen on (see examples). type: list elements: dict purge_listeners: description: - - Purge existing listeners on ELB that are not found in listeners + - Purge existing listeners on ELB that are not found in listeners. type: bool default: yes instance_ids: description: - - List of instance ids to attach to this ELB + - List of instance ids to attach to this ELB. type: list elements: str purge_instance_ids: description: - - Purge existing instance ids on ELB that are not found in instance_ids + - Purge existing instance ids on ELB that are not found in instance_ids. type: bool default: no zones: description: - - List of availability zones to enable on this ELB + - List of availability zones to enable on this ELB. type: list elements: str purge_zones: description: - - Purge existing availability zones on ELB that are not found in zones + - Purge existing availability zones on ELB that are not found in zones. type: bool default: no security_group_ids: description: - - A list of security groups to apply to the elb + - A list of security groups to apply to the ELB. type: list elements: str security_group_names: description: - - A list of security group names to apply to the elb + - A list of security group names to apply to the ELB. type: list elements: str health_check: description: - - An associative array of health check configuration settings (see example) + - An associative array of health check configuration settings (see examples). type: dict access_logs: description: - - An associative array of access logs configuration settings (see example) + - An associative array of access logs configuration settings (see examples). type: dict subnets: description: @@ -83,14 +83,14 @@ elements: str purge_subnets: description: - - Purge existing subnet on ELB that are not found in subnets + - Purge existing subnet on ELB that are not found in subnets. type: bool default: no scheme: description: - - The scheme to use when creating the ELB. For a private VPC-visible ELB use 'internal'. - If you choose to update your scheme with a different value the ELB will be destroyed and - recreated. To update scheme you must use the option wait. + - The scheme to use when creating the ELB. For a private VPC-visible ELB use C(internal). + - If you choose to update your scheme with a different value the ELB will be destroyed and + recreated. To update scheme you must use the option I(wait). type: str choices: ["internal", "internet-facing"] default: 'internet-facing' @@ -101,20 +101,20 @@ default: yes connection_draining_timeout: description: - - Wait a specified timeout allowing connections to drain before terminating an instance + - Wait a specified timeout allowing connections to drain before terminating an instance. type: int idle_timeout: description: - - ELB connections from clients and to servers are timed out after this amount of time + - ELB connections from clients and to servers are timed out after this amount of time. type: int cross_az_load_balancing: description: - - Distribute load across all configured Availability Zones + - Distribute load across all configured Availability Zones. - Defaults to C(false). type: bool stickiness: description: - - An associative array of stickiness policy settings. Policy will be applied to all listeners ( see example ) + - An associative array of stickiness policy settings. Policy will be applied to all listeners (see examples). type: dict wait: description: @@ -124,13 +124,13 @@ default: no wait_timeout: description: - - Used in conjunction with wait. Number of seconds to wait for the elb to be terminated. - A maximum of 600 seconds (10 minutes) is allowed. + - Used in conjunction with wait. Number of seconds to wait for the ELB to be terminated. + - A maximum of 600 seconds (10 minutes) is allowed. type: int default: 60 tags: description: - - An associative array of tags. To delete all tags, supply an empty dict. + - An associative array of tags. To delete all tags, supply an empty dict (C({})). type: dict extends_documentation_fragment: diff --git a/plugins/modules/ec2_vpc_dhcp_option_info.py b/plugins/modules/ec2_vpc_dhcp_option_info.py index 0c0fab9903f..f82f8b3f5ca 100644 --- a/plugins/modules/ec2_vpc_dhcp_option_info.py +++ b/plugins/modules/ec2_vpc_dhcp_option_info.py @@ -12,7 +12,7 @@ version_added: 1.0.0 short_description: Gather information about dhcp options sets in AWS description: - - Gather information about dhcp options sets in AWS + - Gather information about dhcp options sets in AWS. - This module was called C(ec2_vpc_dhcp_option_facts) before Ansible 2.9. The usage did not change. requirements: [ boto3 ] author: "Nick Aslanidis (@naslanidis)" diff --git a/plugins/modules/s3_bucket.py b/plugins/modules/s3_bucket.py index fa250f2383c..3c4f6422c58 100644 --- a/plugins/modules/s3_bucket.py +++ b/plugins/modules/s3_bucket.py @@ -23,19 +23,19 @@ version_added: 1.0.0 short_description: Manage S3 buckets in AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID description: - - Manage S3 buckets in AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID + - Manage S3 buckets in AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID. requirements: [ boto3 ] author: "Rob White (@wimnat)" options: force: description: - When trying to delete a bucket, delete all keys (including versions and delete markers) - in the bucket first (an s3 bucket must be empty for a successful deletion) + in the bucket first (an S3 bucket must be empty for a successful deletion). type: bool default: 'no' name: description: - - Name of the s3 bucket + - Name of the S3 bucket. required: true type: str policy: @@ -44,7 +44,7 @@ type: json s3_url: description: - - S3 URL endpoint for usage with DigitalOcean, Ceph, Eucalyptus and fakes3 etc. + - S3 URL endpoint for usage with DigitalOcean, Ceph, Eucalyptus and FakeS3 etc. - Assumes AWS if not specified. - For Walrus, use FQDN of the endpoint without scheme nor path. aliases: [ S3_URL ] @@ -62,23 +62,23 @@ type: bool state: description: - - Create or remove the s3 bucket + - Create or remove the S3 bucket. required: false default: present choices: [ 'present', 'absent' ] type: str tags: description: - - tags dict to apply to bucket + - Tags dict to apply to bucket. type: dict purge_tags: description: - - whether to remove tags that aren't present in the C(tags) parameter + - Whether to remove tags that aren't present in the I(tags) parameter. type: bool default: True versioning: description: - - Whether versioning is enabled or disabled (note that once versioning is enabled, it can only be suspended) + - Whether versioning is enabled or disabled (note that once versioning is enabled, it can only be suspended). type: bool encryption: description: @@ -87,36 +87,36 @@ choices: [ 'none', 'AES256', 'aws:kms' ] type: str encryption_key_id: - description: KMS master key ID to use for the default encryption. This parameter is allowed if encryption is aws:kms. If + description: KMS master key ID to use for the default encryption. This parameter is allowed if I(encryption) is C(aws:kms). If not specified then it will default to the AWS provided KMS key. type: str public_access: description: - - Configure public access block for S3 bucket - - This option cannot be used together with 'delete_public_access' + - Configure public access block for S3 bucket. + - This option cannot be used together with I(delete_public_access). suboptions: block_public_acls: - description: Sets BlockPublicAcls value + description: Sets BlockPublicAcls value. type: bool default: False block_public_policy: - description: Sets BlockPublicPolicy value + description: Sets BlockPublicPolicy value. type: bool default: False ignore_public_acls: - description: Sets IgnorePublicAcls value + description: Sets IgnorePublicAcls value. type: bool default: False restrict_public_buckets: - description: Sets RestrictPublicAcls value + description: Sets RestrictPublicAcls value. type: bool default: False type: dict version_added: 1.3.0 delete_public_access: description: - - Delete public access block configuration from bucket - - This option cannot be used together with 'public_access' definition + - Delete public access block configuration from bucket. + - This option cannot be used together with a I(public_access) definition. default: false type: bool version_added: 1.3.0 @@ -135,18 +135,18 @@ EXAMPLES = ''' # Note: These examples do not set authentication details, see the AWS Guide for details. -# Create a simple s3 bucket +# Create a simple S3 bucket - amazon.aws.s3_bucket: name: mys3bucket state: present -# Create a simple s3 bucket on Ceph Rados Gateway +# Create a simple S3 bucket on Ceph Rados Gateway - amazon.aws.s3_bucket: name: mys3bucket s3_url: http://your-ceph-rados-gateway-server.xxx ceph: true -# Remove an s3 bucket and any keys it contains +# Remove an S3 bucket and any keys it contains - amazon.aws.s3_bucket: name: mys3bucket state: absent From 2a6bbf046e6836044fc45aab0c254801acc1557a Mon Sep 17 00:00:00 2001 From: Mark Chappell Date: Sun, 6 Dec 2020 08:29:52 +0100 Subject: [PATCH 3/4] Missing full stops Co-authored-by: Felix Fontein --- plugins/modules/aws_s3.py | 2 +- plugins/modules/ec2.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/modules/aws_s3.py b/plugins/modules/aws_s3.py index 3ee2957319a..a7ddc6cf0cd 100644 --- a/plugins/modules/aws_s3.py +++ b/plugins/modules/aws_s3.py @@ -96,7 +96,7 @@ - Force overwrite either locally on the filesystem or remotely with the object/key. Used with PUT and GET operations. - Must be a Boolean, C(always), C(never) or C(different). - C(true) is the same as C(always). - - C(false) is equal to C(never) + - C(false) is equal to C(never). - When this is set to C(different) the MD5 sum of the local file is compared with the 'ETag' of the object/key in S3. The ETag may or may not be an MD5 digest of the object data. See the ETag response header here U(https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html). diff --git a/plugins/modules/ec2.py b/plugins/modules/ec2.py index 7d512bac7a7..9afd039b9f6 100644 --- a/plugins/modules/ec2.py +++ b/plugins/modules/ec2.py @@ -159,7 +159,7 @@ termination_protection: description: - Enable or Disable the Termination Protection. - - Defaults to C(False) + - Defaults to C(false). type: bool instance_initiated_shutdown_behavior: description: From abbd934372bb8e24cb150b0c0a4d259a4739d510 Mon Sep 17 00:00:00 2001 From: Mark Chappell Date: Sun, 6 Dec 2020 08:33:01 +0100 Subject: [PATCH 4/4] Update plugins/modules/ec2.py --- plugins/modules/ec2.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/ec2.py b/plugins/modules/ec2.py index 9afd039b9f6..40adad7f52d 100644 --- a/plugins/modules/ec2.py +++ b/plugins/modules/ec2.py @@ -111,7 +111,7 @@ type: int monitoring: description: - - Enable detailed monitoring (CloudWatch for instance). + - Enable detailed monitoring (CloudWatch) for the instance. type: bool default: false user_data: