From 9e92668d4fc9bb0eeceeb241e2be95c05b18362d Mon Sep 17 00:00:00 2001 From: Mark Chappell Date: Tue, 19 Nov 2019 18:10:19 +0100 Subject: [PATCH] Amazon modules - Yet more minor documentation cleanup (#64930) --- lib/ansible/modules/cloud/amazon/aws_acm.py | 67 +++-- .../modules/cloud/amazon/aws_acm_info.py | 4 + .../aws_config_aggregation_authorization.py | 2 +- .../amazon/aws_config_delivery_channel.py | 2 +- .../cloud/amazon/aws_config_recorder.py | 20 +- .../cloud/amazon/aws_elasticbeanstalk_app.py | 16 +- lib/ansible/modules/cloud/amazon/aws_s3.py | 33 +- .../cloud/amazon/aws_ssm_parameter_store.py | 10 +- .../modules/cloud/amazon/aws_waf_condition.py | 172 +++++++---- .../modules/cloud/amazon/aws_waf_info.py | 20 +- .../modules/cloud/amazon/aws_waf_rule.py | 36 +-- .../modules/cloud/amazon/aws_waf_web_acl.py | 44 +-- .../cloud/amazon/cloudfront_distribution.py | 284 +++++++++--------- .../modules/cloud/amazon/cloudfront_info.py | 12 +- .../cloud/amazon/cloudfront_invalidation.py | 6 +- .../cloudfront_origin_access_identity.py | 12 +- .../cloud/amazon/cloudwatchevent_rule.py | 4 +- .../amazon/dms_replication_subnet_group.py | 7 +- lib/ansible/modules/cloud/amazon/ec2_ami.py | 48 +-- .../modules/cloud/amazon/ec2_ami_copy.py | 2 +- .../modules/cloud/amazon/ec2_ami_info.py | 10 +- .../cloud/amazon/ec2_asg_lifecycle_hook.py | 13 +- .../cloud/amazon/ec2_customer_gateway_info.py | 2 +- 23 files changed, 447 insertions(+), 379 deletions(-) diff --git a/lib/ansible/modules/cloud/amazon/aws_acm.py b/lib/ansible/modules/cloud/amazon/aws_acm.py index baef9f7f788..2d7af9bc4f2 100644 --- a/lib/ansible/modules/cloud/amazon/aws_acm.py +++ b/lib/ansible/modules/cloud/amazon/aws_acm.py @@ -41,34 +41,34 @@ description: This module attempts to restrict such freedoms, to be idempotent, as per the Ansible philosophy. It does this through applying AWS resource "Name" tags to ACM certificates. - > - When C(state=present), + When I(state=present), if there is one certificate in ACM with a C(Name) tag equal to the C(name_tag) parameter, and an identical body and chain, this task will succeed without effect. - > - When C(state=present), + When I(state=present), if there is one certificate in ACM - a C(Name) tag equal to the C(name_tag) parameter, + a I(Name) tag equal to the I(name_tag) parameter, and a different body, this task will overwrite that certificate. - > - When C(state=present), + When I(state=present), if there are multiple certificates in ACM - with a C(Name) tag equal to the C(name_tag) parameter, + with a I(Name) tag equal to the I(name_tag) parameter, this task will fail. - > - When C(state=absent) and C(certificate_arn) is defined, + When I(state=absent) and I(certificate_arn) is defined, this module will delete the ACM resource with that ARN if it exists in this region, and succeed without effect if it doesn't exist. - > - When C(state=absent) and C(domain_name) is defined, + When I(state=absent) and I(domain_name) is defined, this module will delete all ACM resources in this AWS region with a corresponding domain name. If there are none, it will succeed without effect. - > - When C(state=absent) and C(certificate_arn) is not defined, - and C(domain_name) is not defined, - this module will delete all ACM resources in this AWS region with a corresponding C(Name) tag. + When I(state=absent) and I(certificate_arn) is not defined, + and I(domain_name) is not defined, + this module will delete all ACM resources in this AWS region with a corresponding I(Name) tag. If there are none, it will succeed without effect. - Note that this may not work properly with keys of size 4096 bits, due to a limitation of the ACM API. version_added: "2.10" @@ -76,20 +76,20 @@ options: certificate: description: - The body of the PEM encoded public certificate. - - Required when C(state) is not C(absent). + - Required when I(state) is not C(absent). - If your certificate is in a file, use C(lookup('file', 'path/to/cert.pem')). type: str certificate_arn: description: - The ARN of a certificate in ACM to delete - - Ignored when C(state=present). - - If C(state=absent), you must provide one of C(certificate_arn), C(domain_name) or C(name_tag). + - Ignored when I(state=present). + - If I(state=absent), you must provide one of I(certificate_arn), I(domain_name) or I(name_tag). - > - If C(state=absent) and no resource exists with this ARN in this region, + If I(state=absent) and no resource exists with this ARN in this region, the task will succeed with no effect. - > - If C(state=absent) and the corresponding resource exists in a different region, + If I(state=absent) and the corresponding resource exists in a different region, this task may report success without deleting that resource. type: str @@ -97,50 +97,50 @@ options: description: - The body of the PEM encoded chain for your certificate. - If your certificate chain is in a file, use C(lookup('file', 'path/to/chain.pem')). - - Ignored when C(state=absent) + - Ignored when I(state=absent) type: str domain_name: description: - The domain name of the certificate. - > - If C(state=absent) and C(domain_name) is specified, + If I(state=absent) and I(domain_name) is specified, this task will delete all ACM certificates with this domain. - - Exactly one of C(domain_name), C(name_tag) and C(certificate_arn) must be provided. + - Exactly one of I(domain_name), I(name_tag) and I(certificate_arn) must be provided. - > - If C(state=present) this must not be specified. + If I(state=present) this must not be specified. (Since the domain name is encoded within the public certificate's body.) type: str name_tag: description: - - The unique identifier for tagging resources using AWS tags, with key C(Name). + - The unique identifier for tagging resources using AWS tags, with key I(Name). - This can be any set of characters accepted by AWS for tag values. - > This is to ensure Ansible can treat certificates idempotently, even though the ACM API allows duplicate certificates. - - If C(state=preset), this must be specified. + - If I(state=preset), this must be specified. - > - If C(state=absent), you must provide exactly one of - C(certificate_arn), C(domain_name) or C(name_tag). + If I(state=absent), you must provide exactly one of + I(certificate_arn), I(domain_name) or I(name_tag). type: str private_key: description: - The body of the PEM encoded private key. - - Required when C(state) is C(present). - - Ignored when C(state) is C(absent). + - Required when I(state=present). + - Ignored when I(state=absent). - If your private key is in a file, use C(lookup('file', 'path/to/key.pem')). type: str state: description: - > - If C(state=present), the specified public certificate and private key - will be uploaded, with C(Name) tag equal to C(name_tag). + If I(state=present), the specified public certificate and private key + will be uploaded, with I(Name) tag equal to I(name_tag). - > - If C(state=absent), any certificates in this region - with a corresponding C(domain_name), C(name_tag) or C(certificate_arn) + If I(state=absent), any certificates in this region + with a corresponding I(domain_name), I(name_tag) or I(certificate_arn) will be deleted. choices: [present, absent] default: present @@ -201,22 +201,23 @@ RETURN = ''' certificate: description: Information about the certificate which was uploaded type: complex - returned: when C(state) is C(present) + returned: when I(state=present) contains: arn: description: The ARN of the certificate in ACM type: str - returned: when C(state) is C(present) + returned: when I(state=present) sample: "arn:aws:acm:ap-southeast-2:123456789012:certificate/01234567-abcd-abcd-abcd-012345678901" domain_name: description: The domain name encoded within the public certificate type: str - returned: when C(state) is C(present) + returned: when I(state=present) sample: acm.ansible.com arns: description: A list of the ARNs of the certificates in ACM which were deleted type: list - returned: when C(state) is C(absent) + elements: str + returned: when I(state=absent) sample: - "arn:aws:acm:ap-southeast-2:123456789012:certificate/01234567-abcd-abcd-abcd-012345678901" ''' diff --git a/lib/ansible/modules/cloud/amazon/aws_acm_info.py b/lib/ansible/modules/cloud/amazon/aws_acm_info.py index 62f301e8d5e..da32d0374f1 100644 --- a/lib/ansible/modules/cloud/amazon/aws_acm_info.py +++ b/lib/ansible/modules/cloud/amazon/aws_acm_info.py @@ -133,6 +133,7 @@ certificates: - admin@example.com - postmaster@example.com type: list + elements: str validation_status: description: Validation status of the domain returned: always @@ -148,6 +149,7 @@ certificates: returned: always sample: [] type: list + elements: str issued_at: description: Date certificate was issued returned: always @@ -200,6 +202,7 @@ certificates: - admin@example.com - postmaster@example.com type: list + elements: str validation_status: description: Validation status of the domain returned: always @@ -246,6 +249,7 @@ certificates: sample: - '*.example.com' type: list + elements: str tags: description: Tags associated with the certificate returned: always diff --git a/lib/ansible/modules/cloud/amazon/aws_config_aggregation_authorization.py b/lib/ansible/modules/cloud/amazon/aws_config_aggregation_authorization.py index 9e9c7a67b0b..7956e5f1522 100644 --- a/lib/ansible/modules/cloud/amazon/aws_config_aggregation_authorization.py +++ b/lib/ansible/modules/cloud/amazon/aws_config_aggregation_authorization.py @@ -17,7 +17,7 @@ DOCUMENTATION = ''' module: aws_config_aggregation_authorization short_description: Manage cross-account AWS Config authorizations description: - - Module manages AWS Config resources + - Module manages AWS Config resources. version_added: "2.6" requirements: [ 'botocore', 'boto3' ] author: diff --git a/lib/ansible/modules/cloud/amazon/aws_config_delivery_channel.py b/lib/ansible/modules/cloud/amazon/aws_config_delivery_channel.py index 42572328377..cbba196d609 100644 --- a/lib/ansible/modules/cloud/amazon/aws_config_delivery_channel.py +++ b/lib/ansible/modules/cloud/amazon/aws_config_delivery_channel.py @@ -17,7 +17,7 @@ DOCUMENTATION = ''' module: aws_config_delivery_channel short_description: Manage AWS Config delivery channels description: - - This module manages AWS Config delivery locations for rule checks and configuration info + - This module manages AWS Config delivery locations for rule checks and configuration info. version_added: "2.6" requirements: [ 'botocore', 'boto3' ] author: diff --git a/lib/ansible/modules/cloud/amazon/aws_config_recorder.py b/lib/ansible/modules/cloud/amazon/aws_config_recorder.py index 88973ae93e3..2078641898c 100644 --- a/lib/ansible/modules/cloud/amazon/aws_config_recorder.py +++ b/lib/ansible/modules/cloud/amazon/aws_config_recorder.py @@ -17,7 +17,7 @@ DOCUMENTATION = ''' module: aws_config_recorder short_description: Manage AWS Config Recorders description: - - Module manages AWS Config configuration recorder settings + - Module manages AWS Config configuration recorder settings. version_added: "2.6" requirements: [ 'botocore', 'boto3' ] author: @@ -37,33 +37,33 @@ options: role_arn: description: - Amazon Resource Name (ARN) of the IAM role used to describe the AWS resources associated with the account. - - Required when state=present + - Required when I(state=present). type: str recording_group: description: - Specifies the types of AWS resources for which AWS Config records configuration changes. - - Required when state=present + - Required when I(state=present) suboptions: all_supported: description: - Specifies whether AWS Config records configuration changes for every supported type of regional resource. - - If you set this option to `true`, when AWS Config adds support for a new type of regional resource, it starts + - If I(all_supported=true), when AWS Config adds support for a new type of regional resource, it starts recording resources of that type automatically. - - If you set this option to `true`, you cannot enumerate a list of `resource_types`. + - If I(all_supported=true), you cannot enumerate a list of I(resource_types). include_global_types: description: - Specifies whether AWS Config includes all supported types of global resources (for example, IAM resources) with the resources that it records. - - Before you can set this option to `true`, you must set the allSupported option to `true`. - - If you set this option to `true`, when AWS Config adds support for a new type of global resource, it starts recording - resources of that type automatically. - The configuration details for any global resource are the same in all regions. To prevent duplicate configuration items, you should consider customizing AWS Config in only one region to record global resources. + - If you set I(include_global_types=true), you must also set I(all_supported=true). + - If you set I(include_global_types=true), when AWS Config adds support for a new type of global resource, it starts recording + resources of that type automatically. resource_types: description: - A list that specifies the types of AWS resources for which AWS Config records configuration changes (for example, - `AWS::EC2::Instance` or `AWS::CloudTrail::Trail`). - - Before you can set this option to `true`, you must set the `all_supported` option to `false`. + C(AWS::EC2::Instance) or C(AWS::CloudTrail::Trail)). + - Before you can set this option, you must set I(all_supported=false). type: dict extends_documentation_fragment: - aws diff --git a/lib/ansible/modules/cloud/amazon/aws_elasticbeanstalk_app.py b/lib/ansible/modules/cloud/amazon/aws_elasticbeanstalk_app.py index 8fc5be7a17a..cbdf2bdbf32 100644 --- a/lib/ansible/modules/cloud/amazon/aws_elasticbeanstalk_app.py +++ b/lib/ansible/modules/cloud/amazon/aws_elasticbeanstalk_app.py @@ -14,32 +14,32 @@ DOCUMENTATION = ''' --- module: aws_elasticbeanstalk_app -short_description: create, update, and delete an elastic beanstalk application +short_description: Create, update, and delete an elastic beanstalk application version_added: "2.5" description: - - "creates, updates, deletes beanstalk applications if app_name is provided" + - Creates, updates, deletes beanstalk applications if app_name is provided. options: app_name: description: - - name of the beanstalk application you wish to manage + - Name of the beanstalk application you wish to manage. aliases: [ 'name' ] type: str description: description: - - the description of the application + - The description of the application. type: str state: description: - - whether to ensure the application is present or absent + - Whether to ensure the application is present or absent. default: present choices: ['absent','present'] type: str terminate_by_force: description: - - when set to true, running environments will be terminated before deleting the application + - When I(terminate_by_force=true), running environments will be terminated before deleting the application. default: false type: bool author: @@ -66,7 +66,7 @@ EXAMPLES = ''' RETURN = ''' app: - description: beanstalk application + description: Beanstalk application. returned: always type: dict sample: { @@ -81,7 +81,7 @@ app: ] } output: - description: message indicating what change will occur + description: Message indicating what change will occur. returned: in check mode type: str sample: App is up-to-date diff --git a/lib/ansible/modules/cloud/amazon/aws_s3.py b/lib/ansible/modules/cloud/amazon/aws_s3.py index 9cb005f31b9..ff33ee11f1d 100644 --- a/lib/ansible/modules/cloud/amazon/aws_s3.py +++ b/lib/ansible/modules/cloud/amazon/aws_s3.py @@ -35,12 +35,12 @@ options: encrypt: description: - When set for PUT mode, asks for server-side encryption. - default: True + default: true version_added: "2.0" type: bool encryption_mode: description: - - What encryption mode to use if C(encrypt) is set + - What encryption mode to use if I(encrypt=true). default: AES256 choices: - AES256 @@ -49,7 +49,7 @@ options: type: str expiry: description: - - Time limit (in seconds) for the URL generated and returned by S3/Walrus when performing a mode=put or mode=geturl operation. + - Time limit (in seconds) for the URL generated and returned by S3/Walrus when performing a I(mode=put) or I(mode=geturl) operation. default: 600 aliases: ['expiration'] type: int @@ -89,16 +89,16 @@ options: permission: description: - This option lets the user set the canned permissions on the object/bucket that are created. - The permissions that can be set are 'private', 'public-read', 'public-read-write', 'authenticated-read' for a bucket or - 'private', 'public-read', 'public-read-write', 'aws-exec-read', 'authenticated-read', 'bucket-owner-read', - 'bucket-owner-full-control' for an object. Multiple permissions can be specified as a list. + The permissions that can be set are C(private), C(public-read), C(public-read-write), C(authenticated-read) for a bucket or + C(private), C(public-read), C(public-read-write), C(aws-exec-read), C(authenticated-read), C(bucket-owner-read), + C(bucket-owner-full-control) for an object. Multiple permissions can be specified as a list. default: ['private'] version_added: "2.0" type: list elements: str prefix: description: - - Limits the response to keys that begin with the specified prefix for list mode + - Limits the response to keys that begin with the specified prefix for list mode. default: "" version_added: "2.0" type: str @@ -135,11 +135,11 @@ options: - Enables Amazon S3 Dual-Stack Endpoints, allowing S3 communications using both IPv4 and IPv6. - Requires at least botocore version 1.4.45. type: bool - default: "no" + default: false version_added: "2.7" rgw: description: - - Enable Ceph RGW S3 support. This option requires an explicit url via s3_url. + - Enable Ceph RGW S3 support. This option requires an explicit url via I(s3_url). default: false version_added: "2.2" type: bool @@ -152,12 +152,12 @@ options: description: - "Overrides initial bucket lookups in case bucket or iam policies are restrictive. Example: a user may have the GetObject permission but no other permissions. In this case using the option mode: get will fail without specifying - ignore_nonexistent_bucket: True." + I(ignore_nonexistent_bucket=true)." version_added: "2.3" type: bool encryption_kms_key_id: description: - - KMS key id to use when encrypting objects using C(aws:kms) encryption. Ignored if 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) version_added: "2.7" type: str requirements: [ "boto3", "botocore" ] @@ -265,29 +265,30 @@ EXAMPLES = ''' RETURN = ''' msg: - description: msg indicating the status of the operation + description: Message indicating the status of the operation. returned: always type: str sample: PUT operation complete url: - description: url of the object + description: URL of the object. returned: (for put and geturl operations) type: str sample: https://my-bucket.s3.amazonaws.com/my-key.txt?AWSAccessKeyId=&Expires=1506888865&Signature= expiry: - description: number of seconds the presigned url is valid for + description: Number of seconds the presigned url is valid for. returned: (for geturl operation) type: int sample: 600 contents: - description: contents of the object as string + description: Contents of the object as string. returned: (for getstr operation) type: str sample: "Hello, world!" s3_keys: - description: list of object keys + description: List of object keys. returned: (for list operation) type: list + elements: str sample: - prefix1/ - prefix1/key1 diff --git a/lib/ansible/modules/cloud/amazon/aws_ssm_parameter_store.py b/lib/ansible/modules/cloud/amazon/aws_ssm_parameter_store.py index 50d7b6666be..3976468f4d8 100644 --- a/lib/ansible/modules/cloud/amazon/aws_ssm_parameter_store.py +++ b/lib/ansible/modules/cloud/amazon/aws_ssm_parameter_store.py @@ -19,12 +19,12 @@ version_added: "2.5" options: name: description: - - parameter key name. + - Parameter key name. required: true type: str description: description: - - parameter key description. + - Parameter key description. required: false type: str value: @@ -34,15 +34,15 @@ options: type: str state: description: - - Creates or modifies an existing parameter - - Deletes a parameter + - Creates or modifies an existing parameter. + - Deletes a parameter. required: false choices: ['present', 'absent'] default: present type: str string_type: description: - - Parameter String type + - Parameter String type. required: false choices: ['String', 'StringList', 'SecureString'] default: String diff --git a/lib/ansible/modules/cloud/amazon/aws_waf_condition.py b/lib/ansible/modules/cloud/amazon/aws_waf_condition.py index 62e827d8325..f475b3dcd3b 100644 --- a/lib/ansible/modules/cloud/amazon/aws_waf_condition.py +++ b/lib/ansible/modules/cloud/amazon/aws_waf_condition.py @@ -12,7 +12,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = ''' module: aws_waf_condition -short_description: create and delete WAF Conditions +short_description: Create and delete WAF Conditions description: - Read the AWS documentation for WAF U(https://aws.amazon.com/documentation/waf/) @@ -27,10 +27,10 @@ extends_documentation_fragment: options: name: description: Name of the Web Application Firewall condition to manage. - required: yes + required: true type: str type: - description: the type of matching to perform. + description: The type of matching to perform. choices: - byte - geo @@ -43,29 +43,87 @@ options: filters: description: - A list of the filters against which to match. - - For I(type)=C(byte), valid keys are C(field_to_match), C(position), C(header), C(transformation). - - For I(type)=C(geo), the only valid key is C(country). - - For I(type)=C(ip), the only valid key is C(ip_address). - - For I(type)=C(regex), valid keys are C(field_to_match), C(transformation) and C(regex_pattern). - - For I(type)=C(size), valid keys are C(field_to_match), C(transformation), C(comparison) and C(size). - - For I(type)=C(sql), valid keys are C(field_to_match) and C(transformation). - - For I(type)=C(xss), valid keys are C(field_to_match) and C(transformation). - - I(field_to_match) can be one of C(uri), C(query_string), C(header) C(method) and C(body). - - If I(field_to_match) is C(header), then C(header) must also be specified. - - I(transformation) can be one of C(none), C(compress_white_space), C(html_entity_decode), C(lowercase), C(cmd_line), C(url_decode). - - I(position), can be one of C(exactly), C(starts_with), C(ends_with), C(contains), C(contains_word). - - I(comparison) can be one of C(EQ), C(NE), C(LE), C(LT), C(GE), C(GT). - - I(target_string) is a maximum of 50 bytes. - - I(regex_pattern) is a dict with a C(name) key and C(regex_strings) list of strings to match. + - For I(type=byte), valid keys are I(field_to_match), I(position), I(header), I(transformation) and I(target_string). + - For I(type=geo), the only valid key is I(country). + - For I(type=ip), the only valid key is I(ip_address). + - For I(type=regex), valid keys are I(field_to_match), I(transformation) and I(regex_pattern). + - For I(type=size), valid keys are I(field_to_match), I(transformation), I(comparison) and I(size). + - For I(type=sql), valid keys are I(field_to_match) and I(transformation). + - For I(type=xss), valid keys are I(field_to_match) and I(transformation). type: list elements: dict + suboptions: + field_to_match: + description: + - The field upon which to perform the match. + - Valid when I(type=byte), I(type=regex), I(type=sql) or I(type=xss). + type: str + choices: ['uri', 'query_string', 'header', 'method', 'body'] + position: + description: + - Where in the field the match needs to occur. + - Only valid when I(type=byte). + type: str + choices: ['exactly', 'starts_with', 'ends_with', 'contains', 'contains_word'] + header: + description: + - Which specific header should be matched. + - Required when I(field_to_match=header). + - Valid when I(type=byte). + type: str + transformation: + description: + - A transform to apply on the field prior to performing the match. + - Valid when I(type=byte), I(type=regex), I(type=sql) or I(type=xss). + type: str + choices: ['none', 'compress_white_space', 'html_entity_decode', 'lowercase', 'cmd_line', 'url_decode'] + country: + description: + - Value of geo constraint (typically a two letter country code). + - The only valid key when I(type=geo). + type: str + ip_address: + description: + - An IP Address or CIDR to match. + - The only valid key when I(type=ip). + type: str + regex_pattern: + description: + - A dict describing the regular expressions used to perform the match. + - Only valid when I(type=regex). + type: dict + suboptions: + name: + description: A name to describe the set of patterns. + type: str + regex_strings: + description: A list of regular expressions to match. + type: list + elements: str + comparison: + description: + - What type of comparison to perform. + - Only valid key when I(type=size). + type: str + choices: ['EQ', 'NE', 'LE', 'LT', 'GE', 'GT'] + size: + description: + - The size of the field (in bytes). + - Only valid key when I(type=size). + type: int + target_string: + description: + - The string to search for. + - May be up to 50 bytes. + - Valid when I(type=byte). + type: str purge_filters: description: - Whether to remove existing filters from a condition if not passed in I(filters). - default: False + default: false type: bool waf_regional: - description: Whether to use waf_regional module. Defaults to false. + description: Whether to use waf-regional module. default: false required: no type: bool @@ -150,32 +208,32 @@ EXAMPLES = ''' RETURN = ''' condition: - description: condition returned by operation + description: Condition returned by operation. returned: always type: complex contains: condition_id: - description: type-agnostic ID for the condition + description: Type-agnostic ID for the condition. returned: when state is present type: str sample: dd74b1ff-8c06-4a4f-897a-6b23605de413 byte_match_set_id: - description: ID for byte match set + description: ID for byte match set. returned: always type: str sample: c4882c96-837b-44a2-a762-4ea87dbf812b byte_match_tuples: - description: list of byte match tuples + description: List of byte match tuples. returned: always type: complex contains: field_to_match: - description: Field to match + description: Field to match. returned: always type: complex contains: data: - description: Which specific header (if type is header) + description: Which specific header (if type is header). type: str sample: content-type type: @@ -183,32 +241,32 @@ condition: type: str sample: HEADER positional_constraint: - description: Position in the field to match + description: Position in the field to match. type: str sample: STARTS_WITH target_string: - description: String to look for + description: String to look for. type: str sample: Hello text_transformation: - description: Transformation to apply to the field before matching + description: Transformation to apply to the field before matching. type: str sample: NONE geo_match_constraints: - description: List of geographical constraints + description: List of geographical constraints. returned: when type is geo and state is present type: complex contains: type: - description: Type of geo constraint + description: Type of geo constraint. type: str sample: Country value: - description: Value of geo constraint (typically a country code) + description: Value of geo constraint (typically a country code). type: str sample: AT geo_match_set_id: - description: ID of the geo match set + description: ID of the geo match set. returned: when type is geo and state is present type: str sample: dd74b1ff-8c06-4a4f-897a-6b23605de413 @@ -218,46 +276,46 @@ condition: type: complex contains: type: - description: Type of IP address (IPV4 or IPV6) + description: Type of IP address (IPV4 or IPV6). returned: always type: str sample: IPV4 value: - description: IP address + description: IP address. returned: always type: str sample: 10.0.0.0/8 ip_set_id: - description: ID of condition + description: ID of condition. returned: when type is ip and state is present type: str sample: 78ad334a-3535-4036-85e6-8e11e745217b name: - description: Name of condition + description: Name of condition. returned: when state is present type: str sample: my_waf_condition regex_match_set_id: - description: ID of the regex match set + description: ID of the regex match set. returned: when type is regex and state is present type: str sample: 5ea3f6a8-3cd3-488b-b637-17b79ce7089c regex_match_tuples: - description: List of regex matches + description: List of regex matches. returned: when type is regex and state is present type: complex contains: field_to_match: - description: Field on which the regex match is applied + description: Field on which the regex match is applied. type: complex contains: type: - description: The field name + description: The field name. returned: when type is regex and state is present type: str sample: QUERY_STRING regex_pattern_set_id: - description: ID of the regex pattern + description: ID of the regex pattern. type: str sample: 6fdf7f2d-9091-445c-aef2-98f3c051ac9e text_transformation: @@ -265,69 +323,69 @@ condition: type: str sample: NONE size_constraint_set_id: - description: ID of the size constraint set + description: ID of the size constraint set. returned: when type is size and state is present type: str sample: de84b4b3-578b-447e-a9a0-0db35c995656 size_constraints: - description: List of size constraints to apply + description: List of size constraints to apply. returned: when type is size and state is present type: complex contains: comparison_operator: - description: Comparison operator to apply + description: Comparison operator to apply. type: str sample: GT field_to_match: - description: Field on which the size constraint is applied + description: Field on which the size constraint is applied. type: complex contains: type: - description: Field name + description: Field name. type: str sample: QUERY_STRING size: - description: size to compare against the field + description: Size to compare against the field. type: int sample: 300 text_transformation: - description: transformation applied to the text before matching + description: Transformation applied to the text before matching. type: str sample: NONE sql_injection_match_set_id: - description: ID of the SQL injection match set + description: ID of the SQL injection match set. returned: when type is sql and state is present type: str sample: de84b4b3-578b-447e-a9a0-0db35c995656 sql_injection_match_tuples: - description: List of SQL injection match sets + description: List of SQL injection match sets. returned: when type is sql and state is present type: complex contains: field_to_match: - description: Field on which the SQL injection match is applied + description: Field on which the SQL injection match is applied. type: complex contains: type: - description: Field name + description: Field name. type: str sample: QUERY_STRING text_transformation: - description: transformation applied to the text before matching + description: Transformation applied to the text before matching. type: str sample: URL_DECODE xss_match_set_id: - description: ID of the XSS match set + description: ID of the XSS match set. returned: when type is xss and state is present type: str sample: de84b4b3-578b-447e-a9a0-0db35c995656 xss_match_tuples: - description: List of XSS match sets + description: List of XSS match sets. returned: when type is xss and state is present type: complex contains: field_to_match: - description: Field on which the XSS match is applied + description: Field on which the XSS match is applied. type: complex contains: type: @@ -335,7 +393,7 @@ condition: type: str sample: QUERY_STRING text_transformation: - description: transformation applied to the text before matching + description: transformation applied to the text before matching. type: str sample: URL_DECODE ''' diff --git a/lib/ansible/modules/cloud/amazon/aws_waf_info.py b/lib/ansible/modules/cloud/amazon/aws_waf_info.py index c4ba931e8eb..341eb3f96f7 100644 --- a/lib/ansible/modules/cloud/amazon/aws_waf_info.py +++ b/lib/ansible/modules/cloud/amazon/aws_waf_info.py @@ -20,10 +20,10 @@ requirements: [ boto3 ] options: name: description: - - The name of a Web Application Firewall + - The name of a Web Application Firewall. type: str waf_regional: - description: Whether to use waf_regional module. + description: Whether to use the waf-regional module. default: false required: no type: bool @@ -53,12 +53,12 @@ EXAMPLES = ''' RETURN = ''' wafs: - description: The WAFs that match the passed arguments + description: The WAFs that match the passed arguments. returned: success type: complex contains: name: - description: A friendly name or description of the WebACL + description: A friendly name or description of the WebACL. returned: always type: str sample: test_waf @@ -68,34 +68,34 @@ wafs: type: int sample: BLOCK metric_name: - description: A friendly name or description for the metrics for this WebACL + description: A friendly name or description for the metrics for this WebACL. returned: always type: str sample: test_waf_metric rules: - description: An array that contains the action for each Rule in a WebACL , the priority of the Rule + description: An array that contains the action for each Rule in a WebACL , the priority of the Rule. returned: always type: complex contains: action: - description: The action to perform if the Rule matches + description: The action to perform if the Rule matches. returned: always type: str sample: BLOCK metric_name: - description: A friendly name or description for the metrics for this Rule + description: A friendly name or description for the metrics for this Rule. returned: always type: str sample: ipblockrule name: - description: A friendly name or description of the Rule + description: A friendly name or description of the Rule. returned: always type: str sample: ip_block_rule predicates: description: The Predicates list contains a Predicate for each ByteMatchSet, IPSet, SizeConstraintSet, SqlInjectionMatchSet or XssMatchSet - object in a Rule + object in a Rule. returned: always type: list sample: diff --git a/lib/ansible/modules/cloud/amazon/aws_waf_rule.py b/lib/ansible/modules/cloud/amazon/aws_waf_rule.py index 925f78cfdd3..488d390c7bb 100644 --- a/lib/ansible/modules/cloud/amazon/aws_waf_rule.py +++ b/lib/ansible/modules/cloud/amazon/aws_waf_rule.py @@ -12,10 +12,10 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = ''' module: aws_waf_rule -short_description: create and delete WAF Rules +short_description: Create and delete WAF Rules description: - Read the AWS documentation for WAF - U(https://aws.amazon.com/documentation/waf/) + U(https://aws.amazon.com/documentation/waf/). version_added: "2.5" author: @@ -26,18 +26,18 @@ extends_documentation_fragment: - ec2 options: name: - description: Name of the Web Application Firewall rule + description: Name of the Web Application Firewall rule. required: yes type: str metric_name: description: - - A friendly name or description for the metrics for the rule + - A friendly name or description for the metrics for the rule. - The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. - - You can't change metric_name after you create the rule - - Defaults to the same as name with disallowed characters removed + - You can't change I(metric_name) after you create the rule. + - Defaults to the same as I(name) with disallowed characters removed. type: str state: - description: whether the rule should be present or absent + description: Whether the rule should be present or absent. choices: - present - absent @@ -45,8 +45,8 @@ options: type: str conditions: description: > - list of conditions used in the rule. M(aws_waf_condition) can be used to - create new conditions + List of conditions used in the rule. M(aws_waf_condition) can be used to + create new conditions. type: list elements: dict suboptions: @@ -69,9 +69,9 @@ options: default: false type: bool waf_regional: - description: Whether to use waf_regional module. Defaults to false + description: Whether to use waf-regional module. default: false - required: no + required: false type: bool version_added: "2.9" ''' @@ -106,37 +106,37 @@ rule: type: complex contains: metric_name: - description: Metric name for the rule + description: Metric name for the rule. returned: always type: str sample: ansibletest1234rule name: - description: Friendly name for the rule + description: Friendly name for the rule. returned: always type: str sample: ansible-test-1234_rule predicates: - description: List of conditions used in the rule + description: List of conditions used in the rule. returned: always type: complex contains: data_id: - description: ID of the condition + description: ID of the condition. returned: always type: str sample: 8251acdb-526c-42a8-92bc-d3d13e584166 negated: - description: Whether the sense of the condition is negated + description: Whether the sense of the condition is negated. returned: always type: bool sample: false type: - description: type of the condition + description: type of the condition. returned: always type: str sample: ByteMatch rule_id: - description: ID of the WAF rule + description: ID of the WAF rule. returned: always type: str sample: 15de0cbc-9204-4e1f-90e6-69b2f415c261 diff --git a/lib/ansible/modules/cloud/amazon/aws_waf_web_acl.py b/lib/ansible/modules/cloud/amazon/aws_waf_web_acl.py index 07b5ef1318b..4292c487801 100644 --- a/lib/ansible/modules/cloud/amazon/aws_waf_web_acl.py +++ b/lib/ansible/modules/cloud/amazon/aws_waf_web_acl.py @@ -11,10 +11,10 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = ''' module: aws_waf_web_acl -short_description: create and delete WAF Web ACLs +short_description: Create and delete WAF Web ACLs. description: - Read the AWS documentation for WAF - U(https://aws.amazon.com/documentation/waf/) + U(https://aws.amazon.com/documentation/waf/). version_added: "2.5" author: @@ -25,19 +25,19 @@ extends_documentation_fragment: - ec2 options: name: - description: Name of the Web Application Firewall ACL to manage + description: Name of the Web Application Firewall ACL to manage. required: yes type: str default_action: description: The action that you want AWS WAF to take when a request doesn't - match the criteria specified in any of the Rule objects that are associated with the WebACL + match the criteria specified in any of the Rule objects that are associated with the WebACL. choices: - block - allow - count type: str state: - description: whether the Web ACL should be present or absent + description: Whether the Web ACL should be present or absent. choices: - present - absent @@ -45,10 +45,10 @@ options: type: str metric_name: description: - - A friendly name or description for the metrics for this WebACL + - A friendly name or description for the metrics for this WebACL. - The name can contain only alphanumeric characters (A-Z, a-z, 0-9); the name can't contain whitespace. - - You can't change metric_name after you create the WebACL - - Metric name will default to I(name) with disallowed characters stripped out + - You can't change I(metric_name) after you create the WebACL. + - Metric name will default to I(name) with disallowed characters stripped out. type: str rules: description: @@ -61,7 +61,7 @@ options: type: str required: true action: - description: The action to perform + description: The action to perform. type: str required: true priority: @@ -69,18 +69,18 @@ options: type: int required: true type: - description: The type of rule + description: The type of rule. choices: - rate_based - regular type: str purge_rules: description: - - Whether to remove rules that aren't passed with C(rules). + - Whether to remove rules that aren't passed with I(rules). default: False type: bool waf_regional: - description: Whether to use waf_regional module. Defaults to false. + description: Whether to use waf-regional module. default: false required: no type: bool @@ -107,54 +107,54 @@ EXAMPLES = ''' RETURN = ''' web_acl: - description: contents of the Web ACL + description: contents of the Web ACL. returned: always type: complex contains: default_action: - description: Default action taken by the Web ACL if no rules match + description: Default action taken by the Web ACL if no rules match. returned: always type: dict sample: type: BLOCK metric_name: - description: Metric name used as an identifier + description: Metric name used as an identifier. returned: always type: str sample: mywebacl name: - description: Friendly name of the Web ACL + description: Friendly name of the Web ACL. returned: always type: str sample: my web acl rules: - description: List of rules + description: List of rules. returned: always type: complex contains: action: - description: Action taken by the WAF when the rule matches + description: Action taken by the WAF when the rule matches. returned: always type: complex sample: type: ALLOW priority: - description: priority number of the rule (lower numbers are run first) + description: priority number of the rule (lower numbers are run first). returned: always type: int sample: 2 rule_id: - description: Rule ID + description: Rule ID. returned: always type: str sample: a6fc7ab5-287b-479f-8004-7fd0399daf75 type: - description: Type of rule (either REGULAR or RATE_BASED) + description: Type of rule (either REGULAR or RATE_BASED). returned: always type: str sample: REGULAR web_acl_id: - description: Unique identifier of Web ACL + description: Unique identifier of Web ACL. returned: always type: str sample: 10fff965-4b6b-46e2-9d78-24f6d2e2d21c diff --git a/lib/ansible/modules/cloud/amazon/cloudfront_distribution.py b/lib/ansible/modules/cloud/amazon/cloudfront_distribution.py index 30a04bb8c12..896c7803618 100644 --- a/lib/ansible/modules/cloud/amazon/cloudfront_distribution.py +++ b/lib/ansible/modules/cloud/amazon/cloudfront_distribution.py @@ -47,7 +47,7 @@ options: distribution_id: description: - - The id of the CloudFront distribution. + - The ID of the CloudFront distribution. - This parameter can be exchanged with I(alias) or I(caller_reference) and is used in conjunction with I(e_tag). type: str @@ -59,7 +59,7 @@ options: caller_reference: description: - - A unique identifier for creating and updating cloudfront distributions. + - A unique identifier for creating and updating CloudFront distributions. - Each caller reference must be unique across all distributions. e.g. a caller reference used in a web distribution cannot be reused in a streaming distribution. This parameter can be used instead of I(distribution_id) to reference an existing distribution. If not specified, this defaults to a datetime stamp of the format @@ -457,7 +457,7 @@ options: comment: description: - - A comment that describes the cloudfront distribution. + - A comment that describes the CloudFront distribution. - If not specified, it defaults to a generic message that it has been created with Ansible, and a datetime stamp. type: str @@ -554,7 +554,7 @@ options: web_acl_id: description: - - The id of a Web Application Firewall (WAF) Access Control List (ACL). + - The ID of a Web Application Firewall (WAF) Access Control List (ACL). type: str http_version: @@ -644,7 +644,7 @@ EXAMPLES = ''' - cloudfront_distribution: state: present - caller_reference: unique test distribution id + caller_reference: unique test distribution ID origins: - id: 'my test origin-000111' domain_name: www.example.com @@ -676,7 +676,7 @@ EXAMPLES = ''' bucket: mylogbucket.s3.amazonaws.com prefix: myprefix/ enabled: false - comment: this is a cloudfront distribution with logging + comment: this is a CloudFront distribution with logging # delete a distribution @@ -687,272 +687,272 @@ EXAMPLES = ''' RETURN = ''' active_trusted_signers: - description: Key pair IDs that CloudFront is aware of for each trusted signer + description: Key pair IDs that CloudFront is aware of for each trusted signer. returned: always type: complex contains: enabled: - description: Whether trusted signers are in use + description: Whether trusted signers are in use. returned: always type: bool sample: false quantity: - description: Number of trusted signers + description: Number of trusted signers. returned: always type: int sample: 1 items: - description: Number of trusted signers + description: Number of trusted signers. returned: when there are trusted signers type: list sample: - key_pair_id aliases: - description: Aliases that refer to the distribution + description: Aliases that refer to the distribution. returned: always type: complex contains: items: - description: List of aliases + description: List of aliases. returned: always type: list sample: - test.example.com quantity: - description: Number of aliases + description: Number of aliases. returned: always type: int sample: 1 arn: - description: Amazon Resource Name of the distribution + description: Amazon Resource Name of the distribution. returned: always type: str sample: arn:aws:cloudfront::123456789012:distribution/E1234ABCDEFGHI cache_behaviors: - description: Cloudfront cache behaviors + description: CloudFront cache behaviors. returned: always type: complex contains: items: - description: List of cache behaviors + description: List of cache behaviors. returned: always type: complex contains: allowed_methods: - description: Methods allowed by the cache behavior + description: Methods allowed by the cache behavior. returned: always type: complex contains: cached_methods: - description: Methods cached by the cache behavior + description: Methods cached by the cache behavior. returned: always type: complex contains: items: - description: List of cached methods + description: List of cached methods. returned: always type: list sample: - HEAD - GET quantity: - description: Count of cached methods + description: Count of cached methods. returned: always type: int sample: 2 items: - description: List of methods allowed by the cache behavior + description: List of methods allowed by the cache behavior. returned: always type: list sample: - HEAD - GET quantity: - description: Count of methods allowed by the cache behavior + description: Count of methods allowed by the cache behavior. returned: always type: int sample: 2 compress: - description: Whether compression is turned on for the cache behavior + description: Whether compression is turned on for the cache behavior. returned: always type: bool sample: false default_ttl: - description: Default Time to Live of the cache behavior + description: Default Time to Live of the cache behavior. returned: always type: int sample: 86400 forwarded_values: - description: Values forwarded to the origin for this cache behavior + description: Values forwarded to the origin for this cache behavior. returned: always type: complex contains: cookies: - description: Cookies to forward to the origin + description: Cookies to forward to the origin. returned: always type: complex contains: forward: - description: Which cookies to forward to the origin for this cache behavior + description: Which cookies to forward to the origin for this cache behavior. returned: always type: str sample: none whitelisted_names: - description: The names of the cookies to forward to the origin for this cache behavior - returned: when I(forward) is C(whitelist) + description: The names of the cookies to forward to the origin for this cache behavior. + returned: when I(forward=whitelist) type: complex contains: quantity: - description: Count of cookies to forward + description: Count of cookies to forward. returned: always type: int sample: 1 items: - description: List of cookies to forward + description: List of cookies to forward. returned: when list is not empty type: list sample: my_cookie headers: - description: Which headers are used to vary on cache retrievals + description: Which headers are used to vary on cache retrievals. returned: always type: complex contains: quantity: - description: Count of headers to vary on + description: Count of headers to vary on. returned: always type: int sample: 1 items: - description: List of headers to vary on + description: List of headers to vary on. returned: when list is not empty type: list sample: - Host query_string: - description: Whether the query string is used in cache lookups + description: Whether the query string is used in cache lookups. returned: always type: bool sample: false query_string_cache_keys: - description: Which query string keys to use in cache lookups + description: Which query string keys to use in cache lookups. returned: always type: complex contains: quantity: - description: Count of query string cache keys to use in cache lookups + description: Count of query string cache keys to use in cache lookups. returned: always type: int sample: 1 items: - description: List of query string cache keys to use in cache lookups + description: List of query string cache keys to use in cache lookups. returned: when list is not empty type: list sample: lambda_function_associations: - description: Lambda function associations for a cache behavior + description: Lambda function associations for a cache behavior. returned: always type: complex contains: quantity: - description: Count of lambda function associations + description: Count of lambda function associations. returned: always type: int sample: 1 items: - description: List of lambda function associations + description: List of lambda function associations. returned: when list is not empty type: list sample: - lambda_function_arn: arn:aws:lambda:123456789012:us-east-1/lambda/lambda-function event_type: viewer-response max_ttl: - description: Maximum Time to Live + description: Maximum Time to Live. returned: always type: int sample: 31536000 min_ttl: - description: Minimum Time to Live + description: Minimum Time to Live. returned: always type: int sample: 0 path_pattern: - description: Path pattern that determines this cache behavior + description: Path pattern that determines this cache behavior. returned: always type: str sample: /path/to/files/* smooth_streaming: - description: Whether smooth streaming is enabled + description: Whether smooth streaming is enabled. returned: always type: bool sample: false target_origin_id: - description: Id of origin reference by this cache behavior + description: ID of origin reference by this cache behavior. returned: always type: str sample: origin_abcd trusted_signers: - description: Trusted signers + description: Trusted signers. returned: always type: complex contains: enabled: - description: Whether trusted signers are enabled for this cache behavior + description: Whether trusted signers are enabled for this cache behavior. returned: always type: bool sample: false quantity: - description: Count of trusted signers + description: Count of trusted signers. returned: always type: int sample: 1 viewer_protocol_policy: - description: Policy of how to handle http/https + description: Policy of how to handle http/https. returned: always type: str sample: redirect-to-https quantity: - description: Count of cache behaviors + description: Count of cache behaviors. returned: always type: int sample: 1 caller_reference: - description: Idempotency reference given when creating cloudfront distribution + description: Idempotency reference given when creating CloudFront distribution. returned: always type: str sample: '1484796016700' comment: - description: Any comments you want to include about the distribution + description: Any comments you want to include about the distribution. returned: always type: str - sample: 'my first cloudfront distribution' + sample: 'my first CloudFront distribution' custom_error_responses: - description: Custom error responses to use for error handling + description: Custom error responses to use for error handling. returned: always type: complex contains: items: - description: List of custom error responses + description: List of custom error responses. returned: always type: complex contains: error_caching_min_ttl: - description: Minimum time to cache this error response + description: Minimum time to cache this error response. returned: always type: int sample: 300 error_code: - description: Origin response code that triggers this error response + description: Origin response code that triggers this error response. returned: always type: int sample: 500 response_code: - description: Response code to return to the requester + description: Response code to return to the requester. returned: always type: str sample: '500' response_page_path: - description: Path that contains the error page to display + description: Path that contains the error page to display. returned: always type: str sample: /errors/5xx.html @@ -962,310 +962,310 @@ custom_error_responses: type: int sample: 1 default_cache_behavior: - description: Default cache behavior + description: Default cache behavior. returned: always type: complex contains: allowed_methods: - description: Methods allowed by the cache behavior + description: Methods allowed by the cache behavior. returned: always type: complex contains: cached_methods: - description: Methods cached by the cache behavior + description: Methods cached by the cache behavior. returned: always type: complex contains: items: - description: List of cached methods + description: List of cached methods. returned: always type: list sample: - HEAD - GET quantity: - description: Count of cached methods + description: Count of cached methods. returned: always type: int sample: 2 items: - description: List of methods allowed by the cache behavior + description: List of methods allowed by the cache behavior. returned: always type: list sample: - HEAD - GET quantity: - description: Count of methods allowed by the cache behavior + description: Count of methods allowed by the cache behavior. returned: always type: int sample: 2 compress: - description: Whether compression is turned on for the cache behavior + description: Whether compression is turned on for the cache behavior. returned: always type: bool sample: false default_ttl: - description: Default Time to Live of the cache behavior + description: Default Time to Live of the cache behavior. returned: always type: int sample: 86400 forwarded_values: - description: Values forwarded to the origin for this cache behavior + description: Values forwarded to the origin for this cache behavior. returned: always type: complex contains: cookies: - description: Cookies to forward to the origin + description: Cookies to forward to the origin. returned: always type: complex contains: forward: - description: Which cookies to forward to the origin for this cache behavior + description: Which cookies to forward to the origin for this cache behavior. returned: always type: str sample: none whitelisted_names: - description: The names of the cookies to forward to the origin for this cache behavior - returned: when I(forward) is C(whitelist) + description: The names of the cookies to forward to the origin for this cache behavior. + returned: when I(forward=whitelist) type: complex contains: quantity: - description: Count of cookies to forward + description: Count of cookies to forward. returned: always type: int sample: 1 items: - description: List of cookies to forward + description: List of cookies to forward. returned: when list is not empty type: list sample: my_cookie headers: - description: Which headers are used to vary on cache retrievals + description: Which headers are used to vary on cache retrievals. returned: always type: complex contains: quantity: - description: Count of headers to vary on + description: Count of headers to vary on. returned: always type: int sample: 1 items: - description: List of headers to vary on + description: List of headers to vary on. returned: when list is not empty type: list sample: - Host query_string: - description: Whether the query string is used in cache lookups + description: Whether the query string is used in cache lookups. returned: always type: bool sample: false query_string_cache_keys: - description: Which query string keys to use in cache lookups + description: Which query string keys to use in cache lookups. returned: always type: complex contains: quantity: - description: Count of query string cache keys to use in cache lookups + description: Count of query string cache keys to use in cache lookups. returned: always type: int sample: 1 items: - description: List of query string cache keys to use in cache lookups + description: List of query string cache keys to use in cache lookups. returned: when list is not empty type: list sample: lambda_function_associations: - description: Lambda function associations for a cache behavior + description: Lambda function associations for a cache behavior. returned: always type: complex contains: quantity: - description: Count of lambda function associations + description: Count of lambda function associations. returned: always type: int sample: 1 items: - description: List of lambda function associations + description: List of lambda function associations. returned: when list is not empty type: list sample: - lambda_function_arn: arn:aws:lambda:123456789012:us-east-1/lambda/lambda-function event_type: viewer-response max_ttl: - description: Maximum Time to Live + description: Maximum Time to Live. returned: always type: int sample: 31536000 min_ttl: - description: Minimum Time to Live + description: Minimum Time to Live. returned: always type: int sample: 0 path_pattern: - description: Path pattern that determines this cache behavior + description: Path pattern that determines this cache behavior. returned: always type: str sample: /path/to/files/* smooth_streaming: - description: Whether smooth streaming is enabled + description: Whether smooth streaming is enabled. returned: always type: bool sample: false target_origin_id: - description: Id of origin reference by this cache behavior + description: ID of origin reference by this cache behavior. returned: always type: str sample: origin_abcd trusted_signers: - description: Trusted signers + description: Trusted signers. returned: always type: complex contains: enabled: - description: Whether trusted signers are enabled for this cache behavior + description: Whether trusted signers are enabled for this cache behavior. returned: always type: bool sample: false quantity: - description: Count of trusted signers + description: Count of trusted signers. returned: always type: int sample: 1 viewer_protocol_policy: - description: Policy of how to handle http/https + description: Policy of how to handle http/https. returned: always type: str sample: redirect-to-https default_root_object: description: The object that you want CloudFront to request from your origin (for example, index.html) - when a viewer requests the root URL for your distribution + when a viewer requests the root URL for your distribution. returned: always type: str sample: '' diff: - description: Difference between previous configuration and new configuration + description: Difference between previous configuration and new configuration. returned: always type: dict sample: {} domain_name: - description: Domain name of cloudfront distribution + description: Domain name of CloudFront distribution. returned: always type: str sample: d1vz8pzgurxosf.cloudfront.net enabled: - description: Whether the cloudfront distribution is enabled or not + description: Whether the CloudFront distribution is enabled or not. returned: always type: bool sample: true http_version: - description: Version of HTTP supported by the distribution + description: Version of HTTP supported by the distribution. returned: always type: str sample: http2 id: - description: Cloudfront distribution ID + description: CloudFront distribution ID. returned: always type: str sample: E123456ABCDEFG in_progress_invalidation_batches: - description: The number of invalidation batches currently in progress + description: The number of invalidation batches currently in progress. returned: always type: int sample: 0 is_ipv6_enabled: - description: Whether IPv6 is enabled + description: Whether IPv6 is enabled. returned: always type: bool sample: true last_modified_time: - description: Date and time distribution was last modified + description: Date and time distribution was last modified. returned: always type: str sample: '2017-10-13T01:51:12.656000+00:00' logging: - description: Logging information + description: Logging information. returned: always type: complex contains: bucket: - description: S3 bucket logging destination + description: S3 bucket logging destination. returned: always type: str sample: logs-example-com.s3.amazonaws.com enabled: - description: Whether logging is enabled + description: Whether logging is enabled. returned: always type: bool sample: true include_cookies: - description: Whether to log cookies + description: Whether to log cookies. returned: always type: bool sample: false prefix: - description: Prefix added to logging object names + description: Prefix added to logging object names. returned: always type: str sample: cloudfront/test origins: - description: Origins in the cloudfront distribution + description: Origins in the CloudFront distribution. returned: always type: complex contains: items: - description: List of origins + description: List of origins. returned: always type: complex contains: custom_headers: - description: Custom headers passed to the origin + description: Custom headers passed to the origin. returned: always type: complex contains: quantity: - description: Count of headers + description: Count of headers. returned: always type: int sample: 1 custom_origin_config: - description: Configuration of the origin + description: Configuration of the origin. returned: always type: complex contains: http_port: - description: Port on which HTTP is listening + description: Port on which HTTP is listening. returned: always type: int sample: 80 https_port: - description: Port on which HTTPS is listening + description: Port on which HTTPS is listening. returned: always type: int sample: 443 origin_keepalive_timeout: - description: Keep-alive timeout + description: Keep-alive timeout. returned: always type: int sample: 5 origin_protocol_policy: - description: Policy of which protocols are supported + description: Policy of which protocols are supported. returned: always type: str sample: https-only origin_read_timeout: - description: Timeout for reads to the origin + description: Timeout for reads to the origin. returned: always type: int sample: 30 origin_ssl_protocols: - description: SSL protocols allowed by the origin + description: SSL protocols allowed by the origin. returned: always type: complex contains: items: - description: List of SSL protocols + description: List of SSL protocols. returned: always type: list sample: @@ -1273,37 +1273,37 @@ origins: - TLSv1.1 - TLSv1.2 quantity: - description: Count of SSL protocols + description: Count of SSL protocols. returned: always type: int sample: 3 domain_name: - description: Domain name of the origin + description: Domain name of the origin. returned: always type: str sample: test-origin.example.com id: - description: ID of the origin + description: ID of the origin. returned: always type: str sample: test-origin.example.com origin_path: - description: Subdirectory to prefix the request from the S3 or HTTP origin + description: Subdirectory to prefix the request from the S3 or HTTP origin. returned: always type: str sample: '' quantity: - description: Count of origins + description: Count of origins. returned: always type: int sample: 1 price_class: - description: Price class of cloudfront distribution + description: Price class of CloudFront distribution. returned: always type: str sample: PriceClass_All restrictions: - description: Restrictions in use by Cloudfront + description: Restrictions in use by CloudFront. returned: always type: complex contains: @@ -1313,63 +1313,63 @@ restrictions: type: complex contains: quantity: - description: Count of restrictions + description: Count of restrictions. returned: always type: int sample: 1 items: - description: List of country codes allowed or disallowed + description: List of country codes allowed or disallowed. returned: always type: list sample: xy restriction_type: - description: Type of restriction + description: Type of restriction. returned: always type: str sample: blacklist status: - description: Status of the cloudfront distribution + description: Status of the CloudFront distribution. returned: always type: str sample: InProgress tags: - description: Distribution tags + description: Distribution tags. returned: always type: dict sample: Hello: World viewer_certificate: - description: Certificate used by cloudfront distribution + description: Certificate used by CloudFront distribution. returned: always type: complex contains: acm_certificate_arn: - description: ARN of ACM certificate + description: ARN of ACM certificate. returned: when certificate comes from ACM type: str sample: arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-1234-1234-abcd-123456abcdef certificate: - description: Reference to certificate + description: Reference to certificate. returned: always type: str sample: arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-1234-1234-abcd-123456abcdef certificate_source: - description: Where certificate comes from + description: Where certificate comes from. returned: always type: str sample: acm minimum_protocol_version: - description: Minimum SSL/TLS protocol supported by this distribution + description: Minimum SSL/TLS protocol supported by this distribution. returned: always type: str sample: TLSv1 ssl_support_method: - description: Support for pre-SNI browsers or not + description: Support for pre-SNI browsers or not. returned: always type: str sample: sni-only web_acl_id: - description: ID of Web Access Control List (from WAF service) + description: ID of Web Access Control List (from WAF service). returned: always type: str sample: abcd1234-1234-abcd-abcd-abcd12345678 @@ -1499,7 +1499,7 @@ def update_tags(client, module, existing_tags, valid_tags, purge_tags, arn): class CloudFrontValidationManager(object): """ - Manages Cloudfront validations + Manages CloudFront validations """ def __init__(self, module): @@ -2089,7 +2089,7 @@ class CloudFrontValidationManager(object): attempts = 1 + int(wait_timeout / 60) waiter.wait(Id=distribution_id, WaiterConfig={'MaxAttempts': attempts}) except botocore.exceptions.WaiterError as e: - self.module.fail_json(msg="Timeout waiting for cloudfront action. Waited for {0} seconds before timeout. " + self.module.fail_json(msg="Timeout waiting for CloudFront action. Waited for {0} seconds before timeout. " "Error: {1}".format(to_text(wait_timeout), to_native(e))) except (botocore.exceptions.ClientError, botocore.exceptions.BotoCoreError) as e: diff --git a/lib/ansible/modules/cloud/amazon/cloudfront_info.py b/lib/ansible/modules/cloud/amazon/cloudfront_info.py index 58134a43ae9..4845cf779d3 100644 --- a/lib/ansible/modules/cloud/amazon/cloudfront_info.py +++ b/lib/ansible/modules/cloud/amazon/cloudfront_info.py @@ -199,7 +199,7 @@ EXAMPLES = ''' distribution_id: my-cloudfront-distribution-id invalidation_id: my-cloudfront-invalidation-id -# Get all information about a cloudfront origin access identity. +# Get all information about a CloudFront origin access identity. - cloudfront_facts: origin_access_identity: true origin_access_identity_id: my-cloudfront-origin-access-identity-id @@ -225,13 +225,13 @@ origin_access_identity_configuration: type: dict distribution: description: > - Facts about a cloudfront distribution. Requires I(distribution_id) or I(domain_name_alias) + Facts about a CloudFront distribution. Requires I(distribution_id) or I(domain_name_alias) to be specified. Requires I(origin_access_identity_id) to be set. returned: only if distribution is true type: dict distribution_config: description: > - Facts about a cloudfront distribution's config. Requires I(distribution_id) or I(domain_name_alias) + Facts about a CloudFront distribution's config. Requires I(distribution_id) or I(domain_name_alias) to be specified. returned: only if I(distribution_config) is true type: dict @@ -259,7 +259,7 @@ summary: type: dict result: description: > - Result dict not nested under the cloudfront id to access results of module without the knowledge of that id + Result dict not nested under the CloudFront ID to access results of module without the knowledge of that id as figuring out the DistributionId is usually the reason one uses this module in the first place. returned: always type: dict @@ -720,9 +720,9 @@ def main(): result['changed'] = False result['cloudfront'].update(facts) if is_old_facts: - module.exit_json(msg="Retrieved cloudfront facts.", ansible_facts=result) + module.exit_json(msg="Retrieved CloudFront facts.", ansible_facts=result) else: - module.exit_json(msg="Retrieved cloudfront info.", **result) + module.exit_json(msg="Retrieved CloudFront info.", **result) if __name__ == '__main__': diff --git a/lib/ansible/modules/cloud/amazon/cloudfront_invalidation.py b/lib/ansible/modules/cloud/amazon/cloudfront_invalidation.py index 8c0c760576d..e87c84c80dd 100644 --- a/lib/ansible/modules/cloud/amazon/cloudfront_invalidation.py +++ b/lib/ansible/modules/cloud/amazon/cloudfront_invalidation.py @@ -33,7 +33,7 @@ extends_documentation_fragment: options: distribution_id: description: - - The id of the CloudFront distribution to invalidate paths for. Can be specified instead of the alias. + - The ID of the CloudFront distribution to invalidate paths for. Can be specified instead of the alias. required: false type: str alias: @@ -201,7 +201,7 @@ class CloudFrontInvalidationServiceManager(object): invalidation = self.client.get_invalidation(DistributionId=distribution_id, Id=inv_id)['Invalidation'] caller_ref = invalidation.get('InvalidationBatch', {}).get('CallerReference') except (BotoCoreError, ClientError) as e: - self.module.fail_json_aws(e, msg="Error getting Cloudfront invalidation {0}".format(inv_id)) + self.module.fail_json_aws(e, msg="Error getting CloudFront invalidation {0}".format(inv_id)) if caller_ref == caller_reference: current_invalidation = invalidation break @@ -212,7 +212,7 @@ class CloudFrontInvalidationServiceManager(object): class CloudFrontInvalidationValidationManager(object): """ - Manages Cloudfront validations for invalidation batches + Manages CloudFront validations for invalidation batches """ def __init__(self, module): diff --git a/lib/ansible/modules/cloud/amazon/cloudfront_origin_access_identity.py b/lib/ansible/modules/cloud/amazon/cloudfront_origin_access_identity.py index e6ce49f315d..50ff9e3a274 100644 --- a/lib/ansible/modules/cloud/amazon/cloudfront_origin_access_identity.py +++ b/lib/ansible/modules/cloud/amazon/cloudfront_origin_access_identity.py @@ -15,7 +15,7 @@ DOCUMENTATION = ''' module: cloudfront_origin_access_identity short_description: Create, update and delete origin access identities for a - cloudfront distribution + CloudFront distribution description: - Allows for easy creation, updating and deletion of origin access @@ -43,12 +43,12 @@ options: type: str origin_access_identity_id: description: - - The origin_access_identity_id of the cloudfront distribution. + - The origin_access_identity_id of the CloudFront distribution. required: false type: str comment: description: - - A comment to describe the cloudfront origin access identity. + - A comment to describe the CloudFront origin access identity. required: false type: str caller_reference: @@ -108,7 +108,7 @@ cloud_front_origin_access_identity: returned: always type: str s3_canonical_user_id: - description: the canonical user id of the user who created the oai + description: the canonical user ID of the user who created the oai returned: always type: str e_tag: @@ -142,7 +142,7 @@ except ImportError: class CloudFrontOriginAccessIdentityServiceManager(object): """ - Handles cloudfront origin access identity service calls to aws + Handles CloudFront origin access identity service calls to aws """ def __init__(self, module): @@ -205,7 +205,7 @@ class CloudFrontOriginAccessIdentityServiceManager(object): class CloudFrontOriginAccessIdentityValidationManager(object): """ - Manages Cloudfront Origin Access Identities + Manages CloudFront Origin Access Identities """ def __init__(self, module): diff --git a/lib/ansible/modules/cloud/amazon/cloudwatchevent_rule.py b/lib/ansible/modules/cloud/amazon/cloudwatchevent_rule.py index c3e3d5005d9..1a45d24eeeb 100644 --- a/lib/ansible/modules/cloud/amazon/cloudwatchevent_rule.py +++ b/lib/ansible/modules/cloud/amazon/cloudwatchevent_rule.py @@ -137,7 +137,7 @@ EXAMPLES = ''' RETURN = ''' rule: - description: CloudWatch Event rule data + description: CloudWatch Event rule data. returned: success type: dict sample: @@ -147,7 +147,7 @@ rule: schedule_expression: 'cron(0 20 * * ? *)' state: 'ENABLED' targets: - description: CloudWatch Event target(s) assigned to the rule + description: CloudWatch Event target(s) assigned to the rule. returned: success type: list sample: "[{ 'arn': 'arn:aws:lambda:us-east-1:123456789012:function:MyFunction', 'id': 'MyTargetId' }]" diff --git a/lib/ansible/modules/cloud/amazon/dms_replication_subnet_group.py b/lib/ansible/modules/cloud/amazon/dms_replication_subnet_group.py index a98498901c3..96ad4a7c66f 100644 --- a/lib/ansible/modules/cloud/amazon/dms_replication_subnet_group.py +++ b/lib/ansible/modules/cloud/amazon/dms_replication_subnet_group.py @@ -16,12 +16,12 @@ DOCUMENTATION = ''' module: dms_replication_subnet_group short_description: creates or destroys a data migration services subnet group description: - - Creates or destroys a data migration services subnet group + - Creates or destroys a data migration services subnet group. version_added: "2.9" options: state: description: - - State of the subnet group + - State of the subnet group. default: present choices: ['present', 'absent'] type: str @@ -39,8 +39,9 @@ options: subnet_ids: description: - A list containing the subnet ids for the replication subnet group, - needs to be at least 2 items in the list + needs to be at least 2 items in the list. type: list + elements: str author: - "Rui Moreira (@ruimoreira)" extends_documentation_fragment: diff --git a/lib/ansible/modules/cloud/amazon/ec2_ami.py b/lib/ansible/modules/cloud/amazon/ec2_ami.py index d1a04899945..cba62c470dc 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_ami.py +++ b/lib/ansible/modules/cloud/amazon/ec2_ami.py @@ -14,7 +14,7 @@ DOCUMENTATION = ''' --- module: ec2_ami version_added: "1.3" -short_description: create or destroy an image in ec2 +short_description: Create or destroy an image (AMI) in ec2 description: - Registers or deregisters ec2 images. options: @@ -51,7 +51,7 @@ options: wait: description: - Wait for the AMI to be in state 'available' before returning. - default: "no" + default: false type: bool wait_timeout: description: @@ -72,7 +72,7 @@ options: description: - Flag indicating that the bundling process should not attempt to shutdown the instance before bundling. If this flag is True, the responsibility of maintaining file system integrity is left to the owner of the instance. - default: no + default: false type: bool image_id: description: @@ -113,7 +113,7 @@ options: delete_snapshot: description: - Delete snapshots when deregistering the AMI. - default: "no" + default: false type: bool tags: description: @@ -123,7 +123,7 @@ options: purge_tags: description: Whether to remove existing tags that aren't passed in the C(tags) parameter version_added: "2.5" - default: "no" + default: false type: bool launch_permissions: description: @@ -257,12 +257,12 @@ EXAMPLES = ''' RETURN = ''' architecture: - description: architecture of image + description: Architecture of image. returned: when AMI is created or already exists type: str sample: "x86_64" block_device_mapping: - description: block device mapping associated with image + description: Block device mapping associated with image. returned: when AMI is created or already exists type: dict sample: { @@ -275,73 +275,73 @@ block_device_mapping: } } creationDate: - description: creation date of image + description: Creation date of image. returned: when AMI is created or already exists type: str sample: "2015-10-15T22:43:44.000Z" description: - description: description of image + description: Description of image. returned: when AMI is created or already exists type: str sample: "nat-server" hypervisor: - description: type of hypervisor + description: Type of hypervisor. returned: when AMI is created or already exists type: str sample: "xen" image_id: - description: id of the image + description: ID of the image. returned: when AMI is created or already exists type: str sample: "ami-1234abcd" is_public: - description: whether image is public + description: Whether image is public. returned: when AMI is created or already exists type: bool sample: false launch_permission: - description: permissions allowing other accounts to access the AMI + description: Permissions allowing other accounts to access the AMI. returned: when AMI is created or already exists type: list sample: - group: "all" location: - description: location of image + description: Location of image. returned: when AMI is created or already exists type: str sample: "315210894379/nat-server" name: - description: ami name of image + description: AMI name of image. returned: when AMI is created or already exists type: str sample: "nat-server" ownerId: - description: owner of image + description: Owner of image. returned: when AMI is created or already exists type: str sample: "435210894375" platform: - description: platform of image + description: Platform of image. returned: when AMI is created or already exists type: str sample: null root_device_name: - description: root device name of image + description: Root device name of image. returned: when AMI is created or already exists type: str sample: "/dev/sda1" root_device_type: - description: root device type of image + description: Root device type of image. returned: when AMI is created or already exists type: str sample: "ebs" state: - description: state of image + description: State of image. returned: when AMI is created or already exists type: str sample: "available" tags: - description: a dictionary of tags assigned to image + description: A dictionary of tags assigned to image. returned: when AMI is created or already exists type: dict sample: { @@ -349,13 +349,13 @@ tags: "Name": "nat-server" } virtualization_type: - description: image virtualization type + description: Image virtualization type. returned: when AMI is created or already exists type: str sample: "hvm" snapshots_deleted: - description: a list of snapshot ids deleted after deregistering image - returned: after AMI is deregistered, if 'delete_snapshot' is set to 'yes' + description: A list of snapshot ids deleted after deregistering image. + returned: after AMI is deregistered, if I(delete_snapshot=true) type: list sample: [ "snap-fbcccb8f", diff --git a/lib/ansible/modules/cloud/amazon/ec2_ami_copy.py b/lib/ansible/modules/cloud/amazon/ec2_ami_copy.py index 07a65eb25de..989d1b40a58 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_ami_copy.py +++ b/lib/ansible/modules/cloud/amazon/ec2_ami_copy.py @@ -62,7 +62,7 @@ options: type: int tags: description: - - A hash/dictionary of tags to add to the new copied AMI; '{"key":"value"}' and '{"key":"value","key":"value"}' + - 'A hash/dictionary of tags to add to the new copied AMI: C({"key":"value"}) and C({"key":"value","key":"value"})' type: dict tag_equality: description: diff --git a/lib/ansible/modules/cloud/amazon/ec2_ami_info.py b/lib/ansible/modules/cloud/amazon/ec2_ami_info.py index 762354249ea..f83900d9ec9 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_ami_info.py +++ b/lib/ansible/modules/cloud/amazon/ec2_ami_info.py @@ -36,7 +36,7 @@ options: owners: description: - Filter the images by the owner. Valid options are an AWS account ID, self, - - or an AWS owner alias ( amazon | aws-marketplace | microsoft ). + or an AWS owner alias ( amazon | aws-marketplace | microsoft ). aliases: [owner] type: list elements: str @@ -83,9 +83,10 @@ EXAMPLES = ''' RETURN = ''' images: - description: a list of images + description: A list of images. returned: always - type: complex + type: list + elements: dict contains: architecture: description: The architecture of the image. @@ -95,7 +96,8 @@ images: block_device_mappings: description: Any block device mapping entries. returned: always - type: complex + type: list + elements: dict contains: device_name: description: The device name exposed to the instance. 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 0999d16c8b0..61a802ee550 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_asg_lifecycle_hook.py +++ b/lib/ansible/modules/cloud/amazon/ec2_asg_lifecycle_hook.py @@ -15,15 +15,16 @@ DOCUMENTATION = """ module: ec2_asg_lifecycle_hook short_description: Create, delete or update AWS ASG Lifecycle Hooks. description: - - When no given Hook found, will create one. - - In case Hook found, but provided parameters are differes, will update existing Hook. - - In case state=absent and Hook exists, will delete it. + - Will create a new hook when I(state=present) and no given Hook is found. + - Will update an existing hook when I(state=present) and a Hook is found, but current and provided parameters differ. + - Will delete the hook when I(state=absent) and a Hook is found. version_added: "2.5" author: Igor 'Tsigankov' Eyrich (@tsiganenok) options: state: description: - - Create or delete Lifecycle Hook. Present updates existing one or creates if not found. + - 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 @@ -53,8 +54,8 @@ options: description: - The ARN of the notification target that Auto Scaling will use to notify you when an 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. + - 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: diff --git a/lib/ansible/modules/cloud/amazon/ec2_customer_gateway_info.py b/lib/ansible/modules/cloud/amazon/ec2_customer_gateway_info.py index 566a7c93256..96cc73ce452 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_customer_gateway_info.py +++ b/lib/ansible/modules/cloud/amazon/ec2_customer_gateway_info.py @@ -14,7 +14,7 @@ DOCUMENTATION = ''' module: ec2_customer_gateway_info short_description: Gather information about customer gateways in AWS description: - - Gather information about customer gateways in AWS + - Gather information about customer gateways in AWS. - This module was called C(ec2_customer_gateway_facts) before Ansible 2.9. The usage did not change. version_added: "2.5" requirements: [ boto3 ]