diff --git a/changelogs/fragments/documentation_update_5.yml b/changelogs/fragments/documentation_update_5.yml new file mode 100644 index 00000000000..c577d13407d --- /dev/null +++ b/changelogs/fragments/documentation_update_5.yml @@ -0,0 +1,2 @@ +trivial: + - "Part #5 - Ensures the modules documentation follows the correct formats (see also https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation)." diff --git a/plugins/modules/kms_key.py b/plugins/modules/kms_key.py index 1be48988dfc..26c44f1b79f 100644 --- a/plugins/modules/kms_key.py +++ b/plugins/modules/kms_key.py @@ -12,7 +12,7 @@ description: - Manage role/user access to a KMS key. - Not designed for encrypting/decrypting. - - Prior to release 5.0.0 this module was called C(community.aws.aws_kms). + - Prior to release 5.0.0 this module was called M(community.aws.aws_kms). The usage did not change. - This module was originally added to C(community.aws) in release 1.0.0. options: @@ -21,10 +21,10 @@ - An alias for a key. - For safety, even though KMS does not require keys to have an alias, this module expects all new keys to be given an alias to make them easier to manage. Existing keys without an alias - may be referred to by I(key_id). Use M(amazon.aws.kms_key_info) to find key ids. - - Note that passing a I(key_id) and I(alias) will only cause a new alias to be added, an alias will never be renamed. - - The C(alias/) prefix is optional. - - Required if I(key_id) is not given. + may be referred to by O(key_id). Use M(amazon.aws.kms_key_info) to find key ids. + - Note that passing a O(key_id) and O(alias) will only cause a new alias to be added, an alias will never be renamed. + - The V(alias/) prefix is optional. + - Required if O(key_id) is not given. required: false aliases: - key_alias @@ -32,7 +32,7 @@ key_id: description: - Key ID or ARN of the key. - - One of I(alias) or I(key_id) are required. + - One of O(alias) or O(key_id) are required. required: false aliases: - key_arn @@ -45,9 +45,9 @@ state: description: - Whether a key should be present or absent. - - Note that making an existing key C(absent) only schedules a key for deletion. - - Passing a key that is scheduled for deletion with I(state=present) will cancel key deletion. - required: False + - Note that making an existing key V(absent) only schedules a key for deletion. + - Passing a key that is scheduled for deletion with O(state=present) will cancel key deletion. + required: false choices: - present - absent @@ -55,7 +55,7 @@ type: str enabled: description: Whether or not a key is enabled. - default: True + default: true type: bool description: description: @@ -65,14 +65,14 @@ multi_region: description: - Whether to create a multi-Region primary key or not. - default: False + default: false type: bool version_added: 5.5.0 pending_window: description: - The number of days between requesting deletion of the CMK and when it will actually be deleted. - - Only used when I(state=absent) and the CMK has not yet been deleted. - - Valid values are between 7 and 30 (inclusive). + - Only used when O(state=absent) and the CMK has not yet been deleted. + - Valid values are between V(7) and V(30) (inclusive). - 'See also: U(https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html#KMS-ScheduleKeyDeletion-request-PendingWindowInDays)' type: int aliases: ['deletion_delay'] @@ -80,15 +80,15 @@ version_added_collection: community.aws purge_grants: description: - - Whether the I(grants) argument should cause grants not in the list to be removed. - default: False + - Whether the O(grants) argument should cause grants not in the list to be removed. + default: false type: bool grants: description: - - A list of grants to apply to the key. Each item must contain I(grantee_principal). - Each item can optionally contain I(retiring_principal), I(operations), I(constraints), - I(name). - - I(grantee_principal) and I(retiring_principal) must be ARNs + - A list of grants to apply to the key. Each item must contain O(grants.grantee_principal). + Each item can optionally contain O(grants.retiring_principal), O(grants.operations), O(grants.constraints), + O(grants.name). + - O(grants.grantee_principal) and O(grants.retiring_principal) must be ARNs. - 'For full documentation of suboptions see the boto3 documentation:' - 'U(https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/kms.html#KMS.Client.create_grant)' type: list @@ -111,14 +111,19 @@ 'CreateGrant', 'RetireGrant', 'DescribeKey', 'Verify', 'Sign'] constraints: description: - - Constraints is a dict containing C(encryption_context_subset) or C(encryption_context_equals), + - Constraints is a dict containing V(encryption_context_subset) or V(encryption_context_equals), either or both being a dict specifying an encryption context match. See U(https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) or U(https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/kms.html#KMS.Client.create_grant) type: dict + name: + description: + - A friendly name for the grant. + - Use this value to prevent the unintended creation of duplicate grants when retrying this request. + type: str policy: description: - - policy to apply to the KMS key. + - Policy to apply to the KMS key. - See U(https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) type: json key_spec: @@ -256,7 +261,7 @@ deletion_date: description: Date and time after which KMS deletes this KMS key. type: str - returned: when key_state is PendingDeletion + returned: when RV(key_state) is PendingDeletion sample: "2017-04-18T15:12:08.551000+10:00" version_added: 3.3.0 version_added_collection: community.aws @@ -266,7 +271,7 @@ returned: always sample: "My Key for Protecting important stuff" enabled: - description: Whether the key is enabled. True if I(key_state) is C(Enabled). + description: Whether the key is enabled. True if RV(key_state) is V(Enabled). type: bool returned: always sample: false diff --git a/plugins/modules/kms_key_info.py b/plugins/modules/kms_key_info.py index 577dc6b9518..1df7bc4266a 100644 --- a/plugins/modules/kms_key_info.py +++ b/plugins/modules/kms_key_info.py @@ -11,7 +11,7 @@ short_description: Gather information about AWS KMS keys description: - Gather information about AWS KMS keys including tags and grants. - - Prior to release 5.0.0 this module was called C(community.aws.aws_kms_info). + - Prior to release 5.0.0 this module was called M(community.aws.aws_kms_info). The usage did not change. - This module was originally added to C(community.aws) in release 1.0.0. author: @@ -20,7 +20,7 @@ alias: description: - Alias for key. - - Mutually exclusive with I(key_id) and I(filters). + - Mutually exclusive with O(key_id) and O(filters). required: false aliases: - key_alias @@ -30,7 +30,7 @@ key_id: description: - Key ID or ARN of the key. - - Mutually exclusive with I(alias) and I(filters). + - Mutually exclusive with O(alias) and O(filters). required: false aliases: - key_arn @@ -41,13 +41,13 @@ description: - A dict of filters to apply. Each dict item consists of a filter key and a filter value. The filters aren't natively supported by boto3, but are supported to provide similar - functionality to other modules. Standard tag filters (C(tag-key), C(tag-value) and - C(tag:tagName)) are available, as are C(key-id) and C(alias) - - Mutually exclusive with I(alias) and I(key_id). + functionality to other modules. Standard tag filters (V(tag-key), V(tag-value) and + V(tag:tagName)) are available, as are V(key-id) and V(alias) + - Mutually exclusive with O(alias) and O(key_id). type: dict pending_deletion: description: Whether to get full details (tags, grants etc.) of keys pending deletion. - default: False + default: false type: bool notes: - The C(policies) return key was removed in amazon.aws release 8.0.0. @@ -133,7 +133,7 @@ deletion_date: description: Date and time after which KMS deletes this KMS key. type: str - returned: when key_state is PendingDeletion + returned: when RV(kms_keys.key_state) is PendingDeletion sample: "2017-04-18T15:12:08.551000+10:00" version_added: 3.3.0 version_added_collection: community.aws @@ -143,7 +143,7 @@ returned: always sample: "My Key for Protecting important stuff" enabled: - description: Whether the key is enabled. True if I(key_state) is C(Enabled). + description: Whether the key is enabled. True if RV(kms_keys.key_state) is V(Enabled). type: bool returned: always sample: false diff --git a/plugins/modules/lambda.py b/plugins/modules/lambda.py index 5c30b34fd4a..3936850ca0e 100644 --- a/plugins/modules/lambda.py +++ b/plugins/modules/lambda.py @@ -28,14 +28,14 @@ description: - The runtime environment for the Lambda function you are uploading. - Required when creating a function. Uses parameters as described in boto3 docs. - - Required when I(state=present). + - Required when O(state=present). - For supported list of runtimes, see U(https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). type: str role: description: - The Amazon Resource Name (ARN) of the IAM role that Lambda assumes when it executes your function to access any other Amazon Web Services (AWS) resources. You may use the bare ARN if the role belongs to the same AWS account. - - Required when I(state=present). + - Required when O(state=present). type: str handler: description: @@ -44,19 +44,19 @@ zip_file: description: - A .zip file containing your deployment package - - If I(state=present) then either I(zip_file) or I(s3_bucket) must be present. + - If O(state=present) then either O(zip_file) or O(s3_bucket) must be present. aliases: [ 'src' ] type: str s3_bucket: description: - Amazon S3 bucket name where the .zip file containing your deployment package is stored. - - If I(state=present) then either I(zip_file) or I(s3_bucket) must be present. - - I(s3_bucket) and I(s3_key) are required together. + - If O(state=present) then either O(zip_file) or O(s3_bucket) must be present. + - O(s3_bucket) and O(s3_key) are required together. type: str s3_key: description: - The Amazon S3 object (the deployment package) key name you want to upload. - - I(s3_bucket) and I(s3_key) are required together. + - O(s3_bucket) and O(s3_key) are required together. type: str s3_object_version: description: @@ -81,13 +81,13 @@ description: - List of subnet IDs to run Lambda function in. - Use this option if you need to access resources in your VPC. Leave empty if you don't want to run the function in a VPC. - - If set, I(vpc_security_group_ids) must also be set. + - If set, O(vpc_security_group_ids) must also be set. type: list elements: str vpc_security_group_ids: description: - List of VPC security group IDs to associate with the Lambda function. - - Required when I(vpc_subnet_ids) is used. + - Required when O(vpc_subnet_ids) is used. type: list elements: str environment_variables: @@ -112,7 +112,7 @@ architecture: description: - The instruction set architecture that the function supports. - - Requires one of I(s3_bucket) or I(zip_file). + - Requires one of O(s3_bucket) or O(zip_file). type: str choices: ['x86_64', 'arm64'] aliases: ['architectures'] @@ -125,18 +125,18 @@ layer_version_arn: description: - The ARN of the layer version. - - Mutually exclusive with I(layer_version_arn). + - Mutually exclusive with O(layers.layer_name). type: str layer_name: description: - The name or Amazon Resource Name (ARN) of the layer. - - Mutually exclusive with I(layer_version_arn). + - Mutually exclusive with O(layers.layer_version_arn). type: str aliases: ['layer_arn'] version: description: - The version number. - - Required when I(layer_name) is provided, ignored if not. + - Required when O(layers.layer_name) is provided, ignored if not. type: int aliases: ['layer_version'] type: list @@ -146,7 +146,7 @@ description: - The Amazon ECR URI of the image to use. - Required (alternative to runtime zip_file and s3_bucket) when creating a function. - - Required when I(state=present). + - Required when O(state=present). type: str version_added: 7.3.0 author: @@ -241,7 +241,7 @@ type: str sample: 'S3' configuration: - description: the lambda function's configuration metadata returned by get_function in boto3 + description: The Lambda function's configuration metadata returned by get_function in boto3. returned: success type: dict contains: diff --git a/plugins/modules/lambda_alias.py b/plugins/modules/lambda_alias.py index 5b16eebd3aa..a737c05ee82 100644 --- a/plugins/modules/lambda_alias.py +++ b/plugins/modules/lambda_alias.py @@ -11,7 +11,7 @@ short_description: Creates, updates or deletes AWS Lambda function aliases description: - This module allows the management of AWS Lambda functions aliases via the Ansible - framework. It is idempotent and supports "Check" mode. Use module M(amazon.aws.lambda) to manage the lambda function + framework. It is idempotent and supports "Check" mode. Use module M(amazon.aws.lambda) to manage the lambda function itself and M(amazon.aws.lambda_event) to manage event source mappings. - This module was originally added to C(community.aws) in release 1.0.0. @@ -43,7 +43,7 @@ function_version: description: - Version associated with the Lambda function alias. - A value of 0 (or omitted parameter) sets the alias to the $LATEST version. + A value of V(0) (or omitted parameter) sets the alias to the $LATEST version. aliases: ['version'] type: int default: 0 @@ -119,22 +119,22 @@ RETURN = r""" --- alias_arn: - description: Full ARN of the function, including the alias + description: Full ARN of the function, including the alias. returned: success type: str sample: arn:aws:lambda:us-west-2:123456789012:function:myFunction:dev description: - description: A short description of the alias + description: A short description of the alias. returned: success type: str - sample: The development stage for my hot new app + sample: The development stage for my hot new app. function_version: - description: The qualifier that the alias refers to + description: The qualifier that the alias refers to. returned: success type: str sample: $LATEST name: - description: The name of the alias assigned + description: The name of the alias assigned. returned: success type: str sample: dev diff --git a/plugins/modules/lambda_event.py b/plugins/modules/lambda_event.py index 48484c037ae..00519b283e4 100644 --- a/plugins/modules/lambda_event.py +++ b/plugins/modules/lambda_event.py @@ -13,7 +13,7 @@ - This module allows the management of AWS Lambda function event source mappings such as DynamoDB and Kinesis stream events via the Ansible framework. These event source mappings are relevant only in the AWS Lambda pull model, where AWS Lambda invokes the function. - It is idempotent and supports "Check" mode. Use module M(amazon.aws.lambda) to manage the lambda + It is idempotent and supports "Check" mode. Use module M(amazon.aws.lambda) to manage the lambda function itself and M(amazon.aws.lambda_alias) to manage function aliases. - This module was originally added to C(community.aws) in release 1.0.0. @@ -36,19 +36,19 @@ alias: description: - Name of the function alias. - - Mutually exclusive with I(version). + - Mutually exclusive with O(version). type: str version: description: - Version of the Lambda function. - - Mutually exclusive with I(alias). + - Mutually exclusive with O(alias). type: int default: 0 event_source: description: - Source of the event that triggers the lambda function. - - For DynamoDB and Kinesis events, select C(stream) - - For SQS queues, select C(sqs) + - For DynamoDB and Kinesis events, select V(stream). + - For SQS queues, select V(sqs). default: stream choices: ['stream', 'sqs'] type: str @@ -80,7 +80,7 @@ starting_position: description: - The position in the stream where AWS Lambda should start reading. - - Required when I(event_source=stream). + - Required when O(event_source=stream). choices: [TRIM_HORIZON,LATEST] type: str function_response_types: diff --git a/plugins/modules/lambda_execute.py b/plugins/modules/lambda_execute.py index 6b6ff11c538..f77be44a70b 100644 --- a/plugins/modules/lambda_execute.py +++ b/plugins/modules/lambda_execute.py @@ -12,7 +12,7 @@ description: - This module executes AWS Lambda functions, allowing synchronous and asynchronous invocation. - - Prior to release 5.0.0 this module was called C(community.aws.execute_lambda). + - Prior to release 5.0.0 this module was called M(community.aws.execute_lambda). The usage did not change. - This module was originally added to C(community.aws) in release 1.0.0. extends_documentation_fragment: @@ -22,15 +22,15 @@ author: - "Ryan Scott Brown (@ryansb) " notes: - - Async invocation will always return an empty C(output) key. + - Async invocation will always return an empty RV(result.output) key. - Synchronous invocation may result in a function timeout, resulting in an - empty C(output) key. + empty RV(result.output) key. options: name: description: - The name of the function to be invoked. This can only be used for invocations within the calling account. To invoke a function in another - account, use I(function_arn) to specify the full ARN. + account, use O(function_arn) to specify the full ARN. type: str function_arn: description: @@ -38,17 +38,17 @@ type: str tail_log: description: - - If I(tail_log=true), the result of the task will include the last 4 KB + - If O(tail_log=true), the result of the task will include the last 4 KB of the CloudWatch log for the function execution. Log tailing only - works if you use synchronous invocation I(wait=true). This is usually + works if you use synchronous invocation O(wait=true). This is usually used for development or testing Lambdas. type: bool default: false wait: description: - - Whether to wait for the function results or not. If I(wait=no) + - Whether to wait for the function results or not. If O(wait=no) the task will not return any results. To wait for the Lambda function - to complete, set I(wait=true) and the result will be available in the + to complete, set O(wait=true) and the result will be available in the I(output) key. type: bool default: true @@ -62,7 +62,7 @@ version_qualifier: description: - Which version/alias of the function to run. This defaults to the - C(LATEST) revision, but can be set to any existing version or alias. + V(LATEST) revision, but can be set to any existing version or alias. See U(https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html) for details. type: str @@ -116,16 +116,16 @@ type: dict contains: output: - description: Function output if wait=true and the function returns a value + description: Function output if O(wait=true) and the function returns a value. returned: success type: dict sample: "{ 'output': 'something' }" logs: - description: The last 4KB of the function logs. Only provided if I(tail_log) is C(true) + description: The last 4KB of the function logs. Only provided if O(tail_log=true). type: str - returned: if I(tail_log) == true + returned: if O(tail_log=true) status: - description: C(StatusCode) of API call exit (200 for synchronous invokes, 202 for async) + description: V(StatusCode) of API call exit (200 for synchronous invokes, 202 for async). type: int sample: 200 returned: always diff --git a/plugins/modules/lambda_info.py b/plugins/modules/lambda_info.py index 3a7d724e5b8..de889033771 100644 --- a/plugins/modules/lambda_info.py +++ b/plugins/modules/lambda_info.py @@ -18,8 +18,8 @@ query: description: - Specifies the resource type for which to gather information. - - Defaults to C(all) when I(function_name) is specified. - - Defaults to C(config) when I(function_name) is NOT specified. + - Defaults to V(all) when O(function_name) is specified. + - Defaults to V(config) when O(function_name) is NOT specified. choices: [ "aliases", "all", "config", "mappings", "policy", "versions", "tags" ] type: str function_name: @@ -29,7 +29,7 @@ type: str event_source_arn: description: - - When I(query=mappings), this is the Amazon Resource Name (ARN) of the Amazon Kinesis or DynamoDB stream. + - When O(query=mappings), this is the Amazon Resource Name (ARN) of the Amazon Kinesis or DynamoDB stream. type: str author: - Pierre Jodouin (@pjodouin) @@ -70,14 +70,14 @@ --- function: description: - - lambda function list. - - C(function) has been deprecated in will be removed in the next major release after 2025-01-01. + - Lambda function list. + - RV(function) has been deprecated in will be removed in the next major release after 2025-01-01. returned: success type: dict function.TheName: description: - - lambda function information, including event, mapping, and version information. - - C(function) has been deprecated in will be removed in the next major release after 2025-01-01. + - Lambda function information, including event, mapping, and version information. + - RV(function) has been deprecated in will be removed in the next major release after 2025-01-01. returned: success type: dict functions: @@ -90,7 +90,7 @@ contains: aliases: description: The aliases associated with the function. - returned: when C(query) is I(aliases) or I(all) + returned: when O(query=aliases) or O(query=all) type: list elements: str architectures: @@ -179,7 +179,7 @@ sample: '2017-08-01T00:00:00.000+0000' mappings: description: List of configuration information for each event source mapping. - returned: when C(query) is I(all) or I(mappings) + returned: when O(query=all) or O(query=mappings) type: list elements: dict contains: @@ -227,7 +227,7 @@ sample: "Zip" policy: description: The policy associated with the function. - returned: when C(query) is I(all) or I(policy) + returned: when O(query=all) or O(query=policy) type: dict revision_id: description: The latest updated revision of the function or alias. @@ -290,7 +290,7 @@ sample: '1' versions: description: List of Lambda function versions. - returned: when C(query) is I(all) or I(versions) + returned: when O(query=all) or O(query=versions) type: list elements: dict vpc_config: diff --git a/plugins/modules/lambda_layer.py b/plugins/modules/lambda_layer.py index 241915f5a52..33595eed5d1 100644 --- a/plugins/modules/lambda_layer.py +++ b/plugins/modules/lambda_layer.py @@ -14,13 +14,12 @@ - Creates an Lambda layer from a ZIP archive. Each time you call this module with the same layer name, a new version is created. - Deletes a version of an Lambda layer. - author: "Aubin Bikouo (@abikouo)" options: state: description: - - Determines if an Lambda layer should be created, or deleted. When set to C(present), an Lambda layer version will be - created. If set to C(absent), an existing Lambda layer version will be deleted. + - Determines if an Lambda layer should be created, or deleted. When set to V(present), an Lambda layer version will be + created. If set to V(absent), an existing Lambda layer version will be deleted. type: str default: present choices: [ absent, present ] @@ -34,15 +33,15 @@ description: description: - The description of the version. - - Ignored when I(state=absent). - - Mutually exclusive with I(version). + - Ignored when O(state=absent). + - Mutually exclusive with O(version). type: str content: description: - The function layer archive. - - Required when I(state=present). - - Ignored when I(state=absent). - - Mutually exclusive with I(version). + - Required when O(state=present). + - Ignored when O(state=absent). + - Mutually exclusive with o(version). type: dict suboptions: s3_bucket: @@ -64,31 +63,31 @@ compatible_runtimes: description: - A list of compatible function runtimes. - - Ignored when I(state=absent). - - Mutually exclusive with I(version). + - Ignored when O(state=absent). + - Mutually exclusive with O(version). type: list elements: str license_info: description: - The layer's software license. It can be any of an SPDX license identifier, the URL of a license hosted on the internet or the full text of the license. - - Ignored when I(state=absent). - - Mutually exclusive with I(version). + - Ignored when O(state=absent). + - Mutually exclusive with O(version). type: str compatible_architectures: description: - A list of compatible instruction set architectures. For example, x86_64. - - Mutually exclusive with I(version). + - Mutually exclusive with O(version). type: list elements: str version: description: - The version number of the layer to delete. - - Set to C(-1) to delete all versions for the specified layer name. - - Required when I(state=absent). - - Ignored when I(state=present). - - Mutually exclusive with I(description), I(content), I(compatible_runtimes), - I(license_info), I(compatible_architectures). + - Set to V(-1) to delete all versions for the specified layer name. + - Required when O(state=absent). + - Ignored when O(state=present). + - Mutually exclusive with O(description), O(content), O(compatible_runtimes), + O(license_info), O(compatible_architectures). type: int extends_documentation_fragment: - amazon.aws.common.modules @@ -146,29 +145,29 @@ RETURN = r""" layer_version: - description: info about the layer version that was created or deleted. + description: Info about the layer version that was created or deleted. returned: always type: list elements: dict contains: content: description: Details about the layer version. - returned: I(state=present) + returned: O(state=present) type: complex contains: location: description: A link to the layer archive in Amazon S3 that is valid for 10 minutes. - returned: I(state=present) + returned: O(state=present) type: str sample: "https://awslambda-us-east-1-layers.s3.us-east-1.amazonaws.com/snapshots/123456789012/pylayer-9da91deffd3b4941b8baeeae5daeffe4" code_sha256: description: The SHA-256 hash of the layer archive. - returned: I(state=present) + returned: O(state=present) type: str sample: "VLluleJZ3HTwDrdYolSMrS+8iPwEkcoXXaegjXf+dmc=" code_size: description: The size of the layer archive in bytes. - returned: I(state=present) + returned: O(state=present) type: int sample: 9473675 signing_profile_version_arn: @@ -191,7 +190,7 @@ sample: "arn:aws:lambda:eu-west-2:123456789012:layer:pylayer:2" description: description: The description of the version. - returned: I(state=present) + returned: O(state=present) type: str compatible_runtimes: description: A list of compatible runtimes. diff --git a/plugins/modules/lambda_layer_info.py b/plugins/modules/lambda_layer_info.py index 9894a93a2a9..dd8174f835b 100644 --- a/plugins/modules/lambda_layer_info.py +++ b/plugins/modules/lambda_layer_info.py @@ -12,7 +12,6 @@ description: - This module is used to list the versions of an Lambda layer or all available lambda layers. - The lambda layer versions that have been deleted aren't listed. - author: "Aubin Bikouo (@abikouo)" options: name: @@ -24,7 +23,7 @@ version_number: description: - The Lambda layer version number to retrieve. - - Requires I(name) to be provided. + - Requires O(name) to be provided. type: int aliases: - layer_version @@ -32,17 +31,17 @@ compatible_runtime: description: - A runtime identifier. - - Specify this option without I(name) to list only latest layers versions of layers that indicate + - Specify this option without O(name) to list only latest layers versions of layers that indicate that they're compatible with that runtime. - - Specify this option with I(name) to list only layer versions that indicate that + - Specify this option with O(name) to list only layer versions that indicate that they're compatible with that runtime. type: str compatible_architecture: description: - A compatible instruction set architectures. - - Specify this option without I(name) to include only to list only latest layers versions of layers that + - Specify this option without O(name) to include only to list only latest layers versions of layers that are compatible with that instruction set architecture. - - Specify this option with I(name) to include only layer versions that are compatible with that architecture. + - Specify this option with O(name) to include only layer versions that are compatible with that architecture. type: str extends_documentation_fragment: - amazon.aws.common.modules @@ -89,7 +88,7 @@ contains: layer_arn: description: The ARN of the layer. - returned: when C(name) is provided + returned: when O(name) is provided type: str sample: "arn:aws:lambda:eu-west-2:123456789012:layer:pylayer" layer_version_arn: @@ -99,7 +98,7 @@ sample: "arn:aws:lambda:eu-west-2:123456789012:layer:pylayer:2" description: description: The description of the version. - returned: I(state=present) + returned: always type: str created_date: description: The date that the layer version was created, in ISO-8601 format (YYYY-MM-DDThh:mm:ss.sTZD). @@ -127,7 +126,7 @@ type: list content: description: Details about the layer version. - returned: if I(version_number) was provided + returned: if O(version_number) was provided type: complex version_added: 6.0.0 contains: diff --git a/plugins/modules/lambda_policy.py b/plugins/modules/lambda_policy.py index 7fda33292f9..70c32a65cd3 100644 --- a/plugins/modules/lambda_policy.py +++ b/plugins/modules/lambda_policy.py @@ -25,75 +25,65 @@ description: - "Name of the Lambda function whose resource policy you are updating by adding a new permission." - "You can specify a function name (for example, Thumbnail ) or you can specify Amazon Resource Name (ARN) of the" - - "function (for example, C(arn:aws:lambda:us-west-2:account-id:function:ThumbNail) ). AWS Lambda also allows you to" - - "specify partial ARN (for example, C(account-id:Thumbnail) ). Note that the length constraint applies only to the" + - "function (for example, V(arn:aws:lambda:us-west-2:account-id:function:ThumbNail) ). AWS Lambda also allows you to" + - "specify partial ARN (for example, V(account-id:Thumbnail) ). Note that the length constraint applies only to the" - "ARN. If you specify only the function name, it is limited to 64 character in length." required: true aliases: ['lambda_function_arn', 'function_arn'] type: str - state: description: - Describes the desired state. default: "present" choices: ["present", "absent"] type: str - alias: description: - - Name of the function alias. Mutually exclusive with I(version). + - Name of the function alias. Mutually exclusive with O(version). type: str - version: description: - - Version of the Lambda function. Mutually exclusive with I(alias). + - Version of the Lambda function. Mutually exclusive with O(alias). type: int - statement_id: description: - A unique statement identifier. required: true aliases: ['sid'] type: str - action: description: - "The AWS Lambda action you want to allow in this statement. Each Lambda action is a string starting with - lambda: followed by the API name (see Operations ). For example, C(lambda:CreateFunction) . You can use wildcard - (C(lambda:*)) to grant permission for all AWS Lambda actions." + lambda: followed by the API name (see Operations ). For example, V(lambda:CreateFunction) . You can use wildcard + (V(lambda:*)) to grant permission for all AWS Lambda actions." required: true type: str - principal: description: - "The principal who is getting this permission. It can be Amazon S3 service Principal (s3.amazonaws.com ) if you want Amazon S3 to invoke the function, an AWS account ID if you are granting cross-account permission, or - any valid AWS service principal such as sns.amazonaws.com . For example, you might want to allow a custom + any valid AWS service principal such as sns.amazonaws.com. For example, you might want to allow a custom application in another AWS account to push events to AWS Lambda by invoking your function." required: true type: str - source_arn: description: - This is optional; however, when granting Amazon S3 permission to invoke your function, you should specify this field with the bucket Amazon Resource Name (ARN) as its value. This ensures that only events generated from the specified bucket can invoke the function. type: str - source_account: description: - - The AWS account ID (without a hyphen) of the source owner. For example, if I(source_arn) identifies a bucket, + - The AWS account ID (without a hyphen) of the source owner. For example, if O(source_arn) identifies a bucket, then this is the bucket owner's account ID. You can use this additional condition to ensure the bucket you specify is owned by a specific account (it is possible the bucket owner deleted the bucket and some other AWS account created the bucket). You can also use this condition to specify all sources (that is, you don't - specify the I(source_arn) ) owned by a specific account. + specify the O(source_arn)) owned by a specific account. type: str - event_source_token: description: - - Token string representing source ARN or account. Mutually exclusive with I(source_arn) or I(source_account). + - Token string representing source ARN or account. Mutually exclusive with O(source_arn) or O(source_account). type: str - extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -122,7 +112,7 @@ RETURN = r""" --- lambda_policy_action: - description: describes what action was taken + description: Describes what action was taken. returned: success type: str sample: "added" diff --git a/plugins/modules/route53.py b/plugins/modules/route53.py index 6646e8c05e3..c33a42b6573 100644 --- a/plugins/modules/route53.py +++ b/plugins/modules/route53.py @@ -23,12 +23,12 @@ zone: description: - The DNS zone to modify. - - This is a required parameter, if parameter I(hosted_zone_id) is not supplied. + - This is a required parameter, if parameter O(hosted_zone_id) is not supplied. type: str hosted_zone_id: description: - The Hosted Zone ID of the DNS zone to modify. - - This is a required parameter, if parameter I(zone) is not supplied. + - This is a required parameter, if parameter O(zone) is not supplied. type: str record: description: @@ -38,7 +38,7 @@ ttl: description: - The TTL, in second, to give the new record. - - Mutually exclusive with I(alias). + - Mutually exclusive with O(alias). default: 3600 type: int type: @@ -50,8 +50,8 @@ alias: description: - Indicates if this is an alias record. - - Mutually exclusive with I(ttl). - - Defaults to C(false). + - Mutually exclusive with O(ttl). + - Defaults to V(false). type: bool alias_hosted_zone_id: description: @@ -64,7 +64,7 @@ default: false value: description: - - The new value when creating a DNS record. YAML lists or multiple comma-spaced values are allowed for non-alias records. + - The new value when creating a DNS record. YAML lists or multiple comma-spaced values are allowed for non-alias records. type: list elements: str overwrite: @@ -74,12 +74,12 @@ retry_interval: description: - In the case that Route 53 is still servicing a prior request, this module will wait and try again after this many seconds. - If you have many domain names, the default of C(500) seconds may be too long. + If you have many domain names, the default of V(500) seconds may be too long. default: 500 type: int private_zone: description: - - If set to C(true), the private zone matching the requested name within the domain will be used if there are both public and private zones. + - If set to V(true), the private zone matching the requested name within the domain will be used if there are both public and private zones. - The default is to use the public zone. type: bool default: false @@ -94,7 +94,7 @@ have the same combination of DNS name and type, a value that determines what portion of traffic for the current resource record set is routed to the associated location. - - Mutually exclusive with I(region) and I(failover). + - Mutually exclusive with O(region) and O(failover). type: int region: description: @@ -102,7 +102,7 @@ that have the same combination of DNS name and type, a value that determines which region this should be associated with for the latency-based routing - - Mutually exclusive with I(weight) and I(failover). + - Mutually exclusive with O(weight) and O(failover). type: str geo_location: description: @@ -114,7 +114,8 @@ continent_code: description: - The two-letter code for the continent. - - Specifying I(continent_code) with either I(country_code) or I(subdivision_code) returns an InvalidInput error. + - Specifying O(geo_location.continent_code) with either O(geo_location.country_code) or O(geo_location.subdivision_code) + returns an InvalidInput error. type: str country_code: description: @@ -124,7 +125,7 @@ subdivision_code: description: - The two-letter code for a state of the United States. - - To specify I(subdivision_code), I(country_code) must be set to C(US). + - To specify O(geo_location.subdivision_code), O(geo_location.country_code) must be set to V(US). type: str type: dict version_added: 3.3.0 @@ -136,13 +137,13 @@ failover: description: - Failover resource record sets only. Whether this is the primary or - secondary resource record set. Allowed values are PRIMARY and SECONDARY - - Mutually exclusive with I(weight) and I(region). + secondary resource record set. Allowed values are V(PRIMARY) and V(SECONDARY). + - Mutually exclusive with O(weight) and O(region). type: str choices: ['SECONDARY', 'PRIMARY'] vpc_id: description: - - "When used in conjunction with private_zone: true, this will only modify records in the private hosted zone attached to this VPC." + - When used in conjunction with O(private_zone=true), this will only modify records in the private hosted zone attached to this VPC. - This allows you to have multiple private hosted zones, all with the same name, attached to different VPCs. type: str wait: @@ -189,14 +190,14 @@ type: str sample: "PRIMARY" geo_location: - description: geograpic location based on which Route53 resonds to DNS queries. + description: Geograpic location based on which Route53 resonds to DNS queries. returned: when configured type: dict sample: { continent_code: "NA", country_code: "US", subdivision_code: "CA" } version_added: 3.3.0 version_added_collection: community.aws health_check: - description: health_check associated with this record. + description: Health check associated with this record. returned: always type: str identifier: @@ -256,7 +257,7 @@ sample: "foo.bar.com" wait_id: description: - - The wait ID for the applied change. Can be used to wait for the change to propagate later on when I(wait=false). + - The wait ID for the applied change. Can be used to wait for the change to propagate later on when O(wait=false). type: str returned: when changed version_added: 6.3.0 diff --git a/plugins/modules/route53_health_check.py b/plugins/modules/route53_health_check.py index e1d292eb9cb..267a7393c65 100644 --- a/plugins/modules/route53_health_check.py +++ b/plugins/modules/route53_health_check.py @@ -8,11 +8,11 @@ --- module: route53_health_check version_added: 5.0.0 -short_description: Manage health-checks in Amazons Route53 DNS service +short_description: Manage health checks in Amazons Route 53 DNS service description: - - Creates and deletes DNS Health checks in Amazons Route53 service. - - Only the port, resource_path, string_match and request_interval are - considered when updating existing health-checks. + - Creates and deletes DNS Health checks in Amazons Route 53 service. + - Only the O(port), O(resource_path), O(string_match) and O(request_interval) are + considered when updating existing health checks. - This module was originally added to C(community.aws) in release 1.0.0. options: state: @@ -26,13 +26,13 @@ - Stops Route 53 from performing health checks. - See the AWS documentation for more details on the exact implications. U(https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-creating-values.html) - - Defaults to C(true) when creating a new health check. + - Defaults to V(true) when creating a new health check. type: bool version_added: 2.1.0 version_added_collection: community.aws ip_address: description: - - IP address of the end-point to check. Either this or I(fqdn) has to be provided. + - IP address of the end-point to check. Either this or O(fqdn) has to be provided. - IP addresses must be publicly routable. type: str port: @@ -44,8 +44,8 @@ description: - The type of health check that you want to create, which indicates how Amazon Route 53 determines whether an endpoint is healthy. - - Once health_check is created, type can not be changed. - - The CALCULATED choice was added in 6.3.0. + - Once health check is created, type can not be changed. + - The V(CALCULATED) choice was added in 6.3.0. choices: [ 'HTTP', 'HTTPS', 'HTTP_STR_MATCH', 'HTTPS_STR_MATCH', 'TCP', 'CALCULATED' ] type: str child_health_checks: @@ -67,14 +67,14 @@ health checks. The path can be any value for which your endpoint will return an HTTP status code of 2xx or 3xx when the endpoint is healthy, for example the file /docs/route53-health-check.html. - - Mutually exclusive with I(type='TCP'). + - Mutually exclusive with O(type='TCP'). - The path must begin with a / - Maximum 255 characters. type: str fqdn: description: - - Domain name of the endpoint to check. Either this or I(ip_address) has - to be provided. When both are given the I(fqdn) is used in the C(Host:) + - Domain name of the endpoint to check. Either this or O(ip_address) has + to be provided. When both are given the O(fqdn) is used in the V(Host:) header of the HTTP request. type: str string_match: @@ -88,7 +88,7 @@ description: - The number of seconds between the time that Amazon Route 53 gets a response from your endpoint and the time that it sends the next - health-check request. + health check request. default: 30 choices: [ 10, 30 ] type: int @@ -103,17 +103,17 @@ health_check_name: description: - Name of the Health Check. - - Used together with I(use_unique_names) to set/make use of I(health_check_name) as a unique identifier. + - Used together with O(use_unique_names) to set/make use of O(health_check_name) as a unique identifier. type: str - required: False + required: false aliases: ['name'] version_added: 4.1.0 version_added_collection: community.aws use_unique_names: description: - - Used together with I(health_check_name) to set/make use of I(health_check_name) as a unique identifier. + - Used together with O(health_check_name) to set/make use of O(health_check_name) as a unique identifier. type: bool - required: False + required: false version_added: 4.1.0 version_added_collection: community.aws health_check_id: @@ -121,22 +121,22 @@ - ID of the health check to be update or deleted. - If provided, a health check can be updated or deleted based on the ID as unique identifier. type: str - required: False + required: false aliases: ['id'] version_added: 4.1.0 version_added_collection: community.aws measure_latency: description: - To enable/disable latency graphs to monitor the latency between health checkers in multiple Amazon Web Services regions and your endpoint. - - Value of I(measure_latency) is immutable and can not be modified after creating a health check. + - Value of O(measure_latency) is immutable and can not be modified after creating a health check. See U(https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/monitoring-health-check-latency.html) type: bool - required: False + required: false version_added: 5.4.0 author: - "zimbatm (@zimbatm)" notes: - - Support for I(tags) and I(purge_tags) was added in release 2.1.0. + - Support for O(tags) and O(purge_tags) was added in release 2.1.0. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -145,7 +145,7 @@ """ EXAMPLES = r""" -- name: Create a health-check for host1.example.com and use it in record +- name: Create a health check for host1.example.com and use it in record amazon.aws.route53_health_check: state: present fqdn: host1.example.com @@ -187,7 +187,7 @@ use_unique_names: true measure_latency: true -- name: Delete health-check +- name: Delete health check amazon.aws.route53_health_check: state: absent fqdn: host1.example.com diff --git a/plugins/modules/route53_info.py b/plugins/modules/route53_info.py index 909ee0ae370..e09c0e3e6dd 100644 --- a/plugins/modules/route53_info.py +++ b/plugins/modules/route53_info.py @@ -6,16 +6,16 @@ DOCUMENTATION = r""" module: route53_info -short_description: Retrieves route53 details using AWS methods +short_description: Retrieves Route 53 details using AWS methods version_added: 5.0.0 description: - - Gets various details related to Route53 zone, record set or health check details. + - Gets various details related to Route 53 zone, record set or health check details. - This module was originally added to C(community.aws) in release 1.0.0. options: query: description: - Specifies the query action to take. - required: True + required: true choices: [ 'change', 'checker_ip_range', @@ -31,14 +31,14 @@ - The value that you specify here is the value that ChangeResourceRecordSets returned in the Id element when you submitted the request. - - Required if I(query=change). + - Required if O(query=change). required: false type: str hosted_zone_id: description: - The Hosted Zone ID of the DNS zone. - - Required if I(query) is set to I(hosted_zone) and I(hosted_zone_method) is set to I(details). - - Required if I(query) is set to I(record_sets). + - Required if O(query) is set to V(hosted_zone) and O(hosted_zone_method) is set to V(details). + - Required if O(query) is set to V(record_sets). required: false type: str max_items: @@ -49,7 +49,7 @@ next_marker: description: - "Some requests such as list_command: hosted_zones will return a maximum - number of entries - EG 100 or the number specified by I(max_items). + number of entries - EG 100 or the number specified by O(max_items). If the number of entries exceeds this maximum another request can be sent using the NextMarker entry from the first response to get the next page of results." @@ -81,8 +81,8 @@ resource_id: description: - The ID/s of the specified resource/s. - - Required if I(query=health_check) and I(health_check_method=tags). - - Required if I(query=hosted_zone) and I(hosted_zone_method=tags). + - Required if O(query=health_check) and O(health_check_method=tags). + - Required if O(query=hosted_zone) and O(hosted_zone_method=tags). required: false aliases: ['resource_ids'] type: list @@ -90,8 +90,8 @@ health_check_id: description: - The ID of the health check. - - Required if C(query) is set to C(health_check) and - C(health_check_method) is set to C(details) or C(status) or C(failure_reason). + - Required if V(query) is set to V(health_check) and + O(health_check_method) is set to V(details) or V(status) or V(failure_reason). required: false type: str hosted_zone_method: @@ -207,7 +207,7 @@ RETURN = r""" resource_record_sets: description: A list of resource record sets returned by list_resource_record_sets in boto3. - returned: when I(query=record_sets) + returned: when O(query=record_sets) type: list elements: dict contains: @@ -257,7 +257,7 @@ version_added_collection: community.aws hosted_zones: description: A list of hosted zones returned by list_hosted_zones in boto3. - returned: when I(query=hosted_zone) + returned: when O(query=hosted_zone) type: list elements: dict contains: @@ -292,10 +292,10 @@ version_added: 4.0.0 version_added_collection: community.aws health_checks: - description: A list of Route53 health checks returned by list_health_checks in boto3. + description: A list of Route 53 health checks returned by list_health_checks in boto3. type: list elements: dict - returned: when I(query=health_check) + returned: when O(query=health_check) contains: id: description: The identifier that Amazon Route53 assigned to the health check at the time of creation. @@ -322,7 +322,7 @@ type: bool sample: true failure_threshold: - description: The number of consecutive health checks that an endpoint must pass/fail for Route53 to change current status of endpoint. + description: The number of consecutive health checks that an endpoint must pass/fail for Route 53 to change current status of endpoint. type: int sample: 3 fully_qualified_domain_name: @@ -354,7 +354,7 @@ type: str sample: '/welcome.html' search_string: - description: The string that Route53 uses to search for in the response body from specified resource. + description: The string that Route 53 uses to search for in the response body from specified resource. type: str sample: 'test-string-to-match' type: @@ -365,14 +365,14 @@ version_added_collection: community.aws checker_ip_ranges: description: A list of IP ranges in CIDR format for Amazon Route 53 health checkers. - returned: when I(query=checker_ip_range) + returned: when O(query=checker_ip_range) type: list elements: str version_added: 4.1.0 version_added_collection: community.aws delegation_sets: description: A list of dicts that contains information about the reusable delegation set. - returned: when I(query=reusable_delegation_set) + returned: when O(query=reusable_delegation_set) type: list elements: dict version_added: 4.1.0 @@ -380,10 +380,10 @@ health_check: description: A dict of Route53 health check details returned by get_health_check in boto3. type: dict - returned: when I(query=health_check) and I(health_check_method=details) + returned: when O(query=health_check) and O(health_check_method=details) contains: id: - description: The identifier that Amazon Route53 assigned to the health check at the time of creation. + description: The identifier that Amazon Route 53 assigned to the health check at the time of creation. type: str sample: '12345cdc-2cc4-1234-bed2-123456abc1a2' health_check_version: @@ -452,7 +452,7 @@ description: A dict of Route53 health check details returned by get_health_check_status and get_health_check_last_failure_reason in boto3. type: list elements: dict - returned: when I(query=health_check) and I(health_check_method=status) or I(health_check_method=failure_reason) + returned: when O(query=health_check) and O(health_check_method=status) or O(health_check_method=failure_reason) contains: ip_address: description: The IP address of the Amazon Route 53 health checker that provided the failure reason in StatusReport. @@ -479,14 +479,14 @@ description: A deprecated CamelCased list of resource record sets returned by list_resource_record_sets in boto3. \ This list contains same elements/parameters as it's snake_cased version mentioned above. \ This field is deprecated and will be removed in 6.0.0 version release. - returned: when I(query=record_sets) + returned: when O(query=record_sets) type: list elements: dict HostedZones: description: A deprecated CamelCased list of hosted zones returned by list_hosted_zones in boto3. \ This list contains same elements/parameters as it's snake_cased version mentioned above. \ This field is deprecated and will be removed in 6.0.0 version release. - returned: when I(query=hosted_zone) + returned: when O(query=hosted_zone) type: list elements: dict HealthChecks: @@ -495,27 +495,27 @@ This field is deprecated and will be removed in 6.0.0 version release. type: list elements: dict - returned: when I(query=health_check) + returned: when O(query=health_check) CheckerIpRanges: description: A deprecated CamelCased list of IP ranges in CIDR format for Amazon Route 53 health checkers.\ This list contains same elements/parameters as it's snake_cased version mentioned abobe. \ This field is deprecated and will be removed in 6.0.0 version release. type: list elements: str - returned: when I(query=checker_ip_range) + returned: when O(query=checker_ip_range) DelegationSets: description: A deprecated CamelCased list of dicts that contains information about the reusable delegation set. \ This list contains same elements/parameters as it's snake_cased version mentioned above. \ This field is deprecated and will be removed in 6.0.0 version release. type: list elements: dict - returned: when I(query=reusable_delegation_set) + returned: when O(query=reusable_delegation_set) HealthCheck: description: A deprecated CamelCased dict of Route53 health check details returned by get_health_check in boto3. \ This dict contains same elements/parameters as it's snake_cased version mentioned above. \ This field is deprecated and will be removed in 6.0.0 version release. type: dict - returned: when I(query=health_check) and I(health_check_method=details) + returned: when O(query=health_check) and O(health_check_method=details) """ try: diff --git a/plugins/modules/route53_zone.py b/plugins/modules/route53_zone.py index 5bc982d1916..1b20d9261e4 100644 --- a/plugins/modules/route53_zone.py +++ b/plugins/modules/route53_zone.py @@ -6,10 +6,10 @@ DOCUMENTATION = r""" module: route53_zone -short_description: add or delete Route53 zones +short_description: add or delete Route 53 zones version_added: 5.0.0 description: - - Creates and deletes Route53 private and public zones. + - Creates and deletes Route 53 private and public zones. - This module was originally added to C(community.aws) in release 1.0.0. options: zone: @@ -69,7 +69,7 @@ - amazon.aws.tags - amazon.aws.boto3 notes: - - Support for I(tags) and I(purge_tags) was added in release 2.1.0. + - Support for O(tags) and O(purge_tags) was added in release 2.1.0. author: - "Christopher Troup (@minichate)" """ @@ -126,60 +126,60 @@ RETURN = r""" comment: - description: optional hosted zone comment + description: Optional hosted zone comment. returned: when hosted zone exists type: str sample: "Private zone" name: - description: hosted zone name + description: Hosted zone name. returned: when hosted zone exists type: str sample: "private.local." private_zone: - description: whether hosted zone is private or public + description: Whether hosted zone is private or public. returned: when hosted zone exists type: bool sample: true vpc_id: - description: id of the first vpc attached to private hosted zone (use vpcs for associating multiple). + description: Id of the first vpc attached to private hosted zone (use vpcs for associating multiple). returned: for private hosted zone type: str sample: "vpc-1d36c84f" vpc_region: - description: region of the first vpc attached to private hosted zone (use vpcs for assocaiting multiple). + description: Region of the first vpc attached to private hosted zone (use vpcs for assocaiting multiple). returned: for private hosted zone type: str sample: "eu-west-1" vpcs: version_added: 5.3.0 - description: The list of VPCs attached to the private hosted zone + description: The list of VPCs attached to the private hosted zone. returned: for private hosted zone type: list elements: dict sample: "[{'id': 'vpc-123456', 'region': 'us-west-2'}]" contains: id: - description: ID of the VPC + description: ID of the VPC. returned: for private hosted zone type: str sample: "vpc-123456" region: - description: Region of the VPC + description: Region of the VPC. returned: for private hosted zone type: str sample: "eu-west-2" zone_id: - description: hosted zone id + description: Hosted zone id. returned: when hosted zone exists type: str sample: "Z6JQG9820BEFMW" delegation_set_id: - description: id of the associated reusable delegation set + description: Id of the associated reusable delegation set. returned: for public hosted zones, if they have been associated with a reusable delegation set type: str sample: "A1BCDEF2GHIJKL" tags: - description: tags associated with the zone + description: Tags associated with the zone. returned: when tags are defined type: dict """ diff --git a/plugins/modules/s3_bucket.py b/plugins/modules/s3_bucket.py index b27c3acede7..5a66c48c55f 100644 --- a/plugins/modules/s3_bucket.py +++ b/plugins/modules/s3_bucket.py @@ -12,7 +12,7 @@ description: - Manage S3 buckets. - Compatible with AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID. - - When using non-AWS services, I(endpoint_url) should be specified. + - When using non-AWS services, O(endpoint_url) should be specified. author: - Rob White (@wimnat) - Aubin Bikouo (@abikouo) @@ -30,14 +30,14 @@ type: str policy: description: - - The JSON policy as a string. Set to the string C("null") to force the absence of a policy. + - The JSON policy as a string. Set to the string V("null") to force the absence of a policy. type: json ceph: description: - Enable API compatibility with Ceph RGW. - It takes into account the S3 API subset working with Ceph in order to provide the same module behaviour where possible. - - Requires I(endpoint_url) if I(ceph=true). + - Requires O(endpoint_url) if O(ceph=true). aliases: ['rgw'] type: bool default: false @@ -68,78 +68,78 @@ description: - KMS master key ID to use for the default encryption. - If not specified then it will default to the AWS provided KMS key. - - This parameter is only supported if I(encryption) is C(aws:kms). + - This parameter is only supported if O(encryption) is V(aws:kms). type: str bucket_key_enabled: description: - Enable S3 Bucket Keys for SSE-KMS on new objects. - See the AWS documentation for more information U(https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html). - - Bucket Key encryption is only supported if I(encryption=aws:kms). + - Bucket Key encryption is only supported if O(encryption=aws:kms). required: false type: bool version_added: 4.1.0 public_access: description: - Configure public access block for S3 bucket. - - This option cannot be used together with I(delete_public_access). + - This option cannot be used together with O(delete_public_access). - | Note: At the end of April 2023 Amazon updated the default settings to block public access by default. While the defaults for this module remain unchanged, it is necessary to explicitly - pass the I(public_access) parameter to enable public access ACLs. + pass the O(public_access) parameter to enable public access ACLs. suboptions: block_public_acls: description: Sets BlockPublicAcls value. type: bool - default: False + default: false block_public_policy: description: Sets BlockPublicPolicy value. type: bool - default: False + default: false ignore_public_acls: description: Sets IgnorePublicAcls value. type: bool - default: False + default: false restrict_public_buckets: description: Sets RestrictPublicAcls value. type: bool - default: False + 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 a I(public_access) definition. + - This option cannot be used together with a O(public_access) definition. default: false type: bool version_added: 1.3.0 object_ownership: description: - Allow bucket's ownership controls. - - C(BucketOwnerEnforced) - ACLs are disabled and no longer affect access permissions to your + - V(BucketOwnerEnforced) - ACLs are disabled and no longer affect access permissions to your bucket. Requests to set or update ACLs fail. However, requests to read ACLs are supported. Bucket owner has full ownership and control. Object writer no longer has full ownership and control. - - C(BucketOwnerPreferred) - Objects uploaded to the bucket change ownership to the bucket owner + - V(BucketOwnerPreferred) - Objects uploaded to the bucket change ownership to the bucket owner if the objects are uploaded with the bucket-owner-full-control canned ACL. - - C(ObjectWriter) - The uploading account will own the object + - V(ObjectWriter) - The uploading account will own the object if the object is uploaded with the bucket-owner-full-control canned ACL. - - This option cannot be used together with a I(delete_object_ownership) definition. - - C(BucketOwnerEnforced) has been added in version 3.2.0. - - "Note: At the end of April 2023 Amazon updated the default setting to C(BucketOwnerEnforced)." + - This option cannot be used together with a O(delete_object_ownership) definition. + - V(BucketOwnerEnforced) has been added in version 3.2.0. + - "Note: At the end of April 2023 Amazon updated the default setting to V(BucketOwnerEnforced)." choices: [ 'BucketOwnerEnforced', 'BucketOwnerPreferred', 'ObjectWriter' ] type: str version_added: 2.0.0 object_lock_enabled: description: - Whether S3 Object Lock to be enabled. - - Defaults to C(False) when creating a new bucket. + - Defaults to V(false) when creating a new bucket. type: bool version_added: 5.3.0 delete_object_ownership: description: - Delete bucket's ownership controls. - - This option cannot be used together with a I(object_ownership) definition. + - This option cannot be used together with a O(object_ownership) definition. default: false type: bool version_added: 2.0.0 @@ -158,11 +158,11 @@ - See https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html type: bool version_added: 3.1.0 - default: True + default: true dualstack: description: - Enables Amazon S3 Dual-Stack Endpoints, allowing S3 communications using both IPv4 and IPv6. - - Mutually exclusive with I(endpoint_url). + - Mutually exclusive with O(endpoint_url). type: bool default: false version_added: 6.0.0 @@ -177,13 +177,13 @@ - If C(requestPayment), C(policy), C(tagging) or C(versioning) operations/API aren't implemented by the endpoint, module doesn't fail if each parameter satisfies the following condition. - I(requester_pays) is C(False), I(policy), I(tags), and I(versioning) are C(None). - - In release 5.0.0 the I(s3_url) parameter was merged into the I(endpoint_url) parameter, - I(s3_url) remains as an alias for I(endpoint_url). - - For Walrus I(endpoint_url) should be set to the FQDN of the endpoint with neither scheme nor path. - - Support for the C(S3_URL) environment variable has been - deprecated and will be removed in a release after 2024-12-01, please use the I(endpoint_url) parameter - or the C(AWS_URL) environment variable. + O(requester_pays) is V(false), O(policy), O(tags), and O(versioning) are V(None). + - In release 5.0.0 the O(s3_url) parameter was merged into the O(endpoint_url) parameter, + O(s3_url) remains as an alias for O(endpoint_url). + - For Walrus O(endpoint_url) should be set to the FQDN of the endpoint with neither scheme nor path. + - Support for the E(S3_URL) environment variable has been + deprecated and will be removed in a release after 2024-12-01, please use the O(endpoint_url) parameter + or the E(AWS_URL) environment variable. """ EXAMPLES = r""" diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py index acae57a2826..07d2f226949 100644 --- a/plugins/modules/s3_bucket_info.py +++ b/plugins/modules/s3_bucket_info.py @@ -14,7 +14,7 @@ short_description: Lists S3 buckets in AWS description: - Lists S3 buckets and details about those buckets. - - Prior to release 5.0.0 this module was called C(community.aws.aws_s3_bucket_info). + - Prior to release 5.0.0 this module was called M(community.aws.aws_s3_bucket_info). The usage did not change. options: name: @@ -25,15 +25,15 @@ version_added: 1.4.0 name_filter: description: - - Limits buckets to only buckets who's name contain the string in I(name_filter). + - Limits buckets to only buckets who's name contain the string in O(name_filter). type: str default: "" version_added: 1.4.0 bucket_facts: description: - Retrieve requested S3 bucket detailed information. - - Each bucket_X option executes one API call, hence many options being set to C(true) will cause slower module execution. - - You can limit buckets by using the I(name) or I(name_filter) option. + - Each bucket_X option executes one API call, hence many options being set to V(true) will cause slower module execution. + - You can limit buckets by using the O(name) or O(name_filter) option. suboptions: bucket_accelerate_configuration: description: Retrieve S3 accelerate configuration. @@ -112,8 +112,8 @@ transform_location: description: - S3 bucket location for default us-east-1 is normally reported as C(null). - - Setting this option to C(true) will return C(us-east-1) instead. - - Affects only queries with I(bucket_facts=true) and I(bucket_location=true). + - Setting this option to V(true) will return V(us-east-1) instead. + - Affects only queries with O(bucket_facts=true) and O(bucket_facts.bucket_location=true). type: bool default: False version_added: 1.4.0 diff --git a/plugins/modules/s3_object.py b/plugins/modules/s3_object.py index e08903b7ddd..df6b08ce039 100644 --- a/plugins/modules/s3_object.py +++ b/plugins/modules/s3_object.py @@ -15,7 +15,7 @@ strings, generating download links and copying objects that are already stored in Amazon S3. - S3 buckets can be created or deleted using the M(amazon.aws.s3_bucket) module. - Compatible with AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID. - - When using non-AWS services, I(endpoint_url) should be specified. + - When using non-AWS services, O(endpoint_url) should be specified. options: bucket: description: @@ -24,18 +24,18 @@ type: str dest: description: - - The destination file path when downloading an object/key when I(mode=get). - - Ignored when I(mode) is not C(get). + - The destination file path when downloading an object/key when O(mode=get). + - Ignored when O(mode) is not V(get). type: path encrypt: description: - - Asks for server-side encryption of the objects when I(mode=put) or I(mode=copy). - - Ignored when I(mode) is neither C(put) nor C(copy). + - Asks for server-side encryption of the objects when O(mode=put) or O(mode=copy). + - Ignored when O(mode) is neither V(put) nor V(copy). default: true type: bool encryption_mode: description: - - The encryption mode to use if I(encrypt=true). + - The encryption mode to use if O(encrypt=true). default: AES256 choices: - AES256 @@ -44,15 +44,15 @@ expiry: description: - Time limit (in seconds) for the URL generated and returned by S3/Walrus when performing a - I(mode=put) or I(mode=geturl) operation. - - Ignored when I(mode) is neither C(put) nor C(geturl). + O(mode=put) or O(mode=geturl) operation. + - Ignored when O(mode) is neither V(put) nor V(geturl). default: 600 aliases: ['expiration'] type: int headers: description: - - Custom headers to use when I(mode=put) as a dictionary of key value pairs. - - Ignored when I(mode) is not C(put). + - Custom headers to use when O(mode=put) as a dictionary of key value pairs. + - Ignored when O(mode) is not V(put). type: dict marker: description: @@ -62,26 +62,26 @@ default: '' max_keys: description: - - Max number of results to return when I(mode=list), set this if you want to retrieve fewer + - Max number of results to return when O(mode=list), set this if you want to retrieve fewer than the default 1000 keys. - - Ignored when I(mode) is not C(list). + - Ignored when O(mode) is not V(list). default: 1000 type: int metadata: description: - - Metadata to use when I(mode=put) or I(mode=copy) as a dictionary of key value pairs. + - Metadata to use when O(mode=put) or O(mode=copy) as a dictionary of key value pairs. type: dict mode: description: - Switches the module behaviour between - - 'C(put): upload' - - 'C(get): download' - - 'C(geturl): return download URL' - - 'C(getstr): download object as string' - - 'C(list): list keys' - - 'C(create): create bucket directories' - - 'C(delobj): delete object' - - 'C(copy): copy object that is already stored in another bucket' + - 'V(put): upload' + - 'V(get): download' + - 'V(geturl): return download URL' + - 'V(getstr): download object as string' + - 'V(list): list keys' + - 'V(create): create bucket directories' + - 'V(delobj): delete object' + - 'V(copy): copy object that is already stored in another bucket' - Support for creating and deleting buckets was removed in release 6.0.0. To create and manage the bucket itself please use the M(amazon.aws.s3_bucket) module. required: true @@ -94,22 +94,22 @@ - Object key names should not include the leading C(/), see U(https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html) for more information. - - Support for passing the leading C(/) has been deprecated and will be removed + - Support for passing the leading V(/) has been deprecated and will be removed in a release after 2025-12-01. type: str sig_v4: description: - Forces the Boto SDK to use Signature Version 4. - - Only applies to get modes, I(mode=get), I(mode=getstr), I(mode=geturl). + - Only applies to get modes, O(mode=get), O(mode=getstr), O(mode=geturl). default: true type: bool version_added: 5.0.0 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 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) + The permissions that can be set are V(private), V(public-read), V(public-read-write), + V(authenticated-read) for a bucket or V(private), V(public-read), V(public-read-write), + V(aws-exec-read), V(authenticated-read), V(bucket-owner-read), V(bucket-owner-full-control) for an object. Multiple permissions can be specified as a list; although only the first one will be used during the initial upload of the file. - For a full list of permissions see the AWS documentation @@ -138,16 +138,16 @@ overwrite: description: - Force overwrite either locally on the filesystem or remotely with the object/key. - - Used when I(mode=put) or I(mode=get). - - Ignored when when I(mode) is neither C(put) nor C(get). - - Must be a Boolean, C(always), C(never), C(different) or C(latest). - - C(true) is the same as C(always). - - C(false) is equal to C(never). + - Used when O(mode=put) or O(mode=get). + - Ignored when when O(mode) is neither V(put) nor V(get). + - Must be a Boolean, V(always), V(never), V(different) or V(latest). + - V(true) is the same as V(always). + - V(false) is equal to V(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). - - When I(mode=get) and I(overwrite=latest) the last modified timestamp of local file + - When O(mode=get) and O(overwrite=latest) the last modified timestamp of local file is compared with the 'LastModified' of the object/key in S3. default: 'different' aliases: ['force'] @@ -161,8 +161,8 @@ dualstack: description: - Enables Amazon S3 Dual-Stack Endpoints, allowing S3 communications using both IPv4 and IPv6. - - Support for passing I(dualstack) and I(endpoint_url) at the same time has been deprecated, - the dualstack endpoints are automatically configured using the configured I(region). + - Support for passing O(dualstack) and O(endpoint_url) at the same time has been deprecated, + the dualstack endpoints are automatically configured using the configured O(region). Support will be removed in a release after 2024-12-01. type: bool default: false @@ -171,14 +171,14 @@ - Enable API compatibility with Ceph RGW. - It takes into account the S3 API subset working with Ceph in order to provide the same module behaviour where possible. - - Requires I(endpoint_url) if I(ceph=true). + - Requires O(endpoint_url) if O(ceph=true). aliases: ['rgw'] default: false type: bool src: description: - The source file path when performing a C(put) operation. - - One of I(content), I(content_base64) or I(src) must be specified when I(mode=put) + - One of O(content), O(content_base64) or O(src) must be specified when O(mode=put) otherwise ignored. type: path content: @@ -186,8 +186,8 @@ - The content to C(put) into an object. - The parameter value will be treated as a string and converted to UTF-8 before sending it to S3. - - To send binary data, use the I(content_base64) parameter instead. - - One of I(content), I(content_base64) or I(src) must be specified when I(mode=put) + - To send binary data, use the O(content_base64) parameter instead. + - One of O(content), O(content_base64) or O(src) must be specified when O(mode=put) otherwise ignored. version_added: "1.3.0" type: str @@ -195,7 +195,7 @@ description: - The base64-encoded binary data to C(put) into an object. - Use this if you need to put raw binary data, and don't forget to encode in base64. - - One of I(content), I(content_base64) or I(src) must be specified when I(mode=put) + - One of O(content), O(content_base64) or O(src) must be specified when O(mode=put) otherwise ignored. version_added: "1.3.0" type: str @@ -203,19 +203,19 @@ description: - Overrides initial bucket lookups in case bucket or IAM policies are restrictive. - This can be useful when a user may have the C(GetObject) permission but no other - permissions. In which case using I(mode=get) will fail unless - I(ignore_nonexistent_bucket=true) is specified. + permissions. In which case using O(mode=get) will fail unless + O(ignore_nonexistent_bucket=true) is specified. 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). + - KMS key id to use when encrypting objects using O(encryption_mode=aws:kms). + - Ignored if O(encryption_mode) is not V(aws:kms). type: str copy_src: description: - The source details of the object to copy. - - Required if I(mode=copy). + - Required if O(mode=copy). type: dict version_added: 2.0.0 suboptions: @@ -228,7 +228,7 @@ type: str description: - key name of the source object. - - if not specified, all the objects of the I(copy_src.bucket) will be copied into the specified bucket. + - if not specified, all the objects of the O(copy_src.bucket) will be copied into the specified bucket. required: false version_id: type: str @@ -237,7 +237,7 @@ prefix: description: - Copy all the keys that begin with the specified prefix. - - Ignored if I(copy_src.object) is supplied. + - Ignored if O(copy_src.object) is supplied. default: "" type: str version_added: 6.2.0 @@ -255,13 +255,13 @@ - "Sloane Hertel (@s-hertel)" - "Alina Buzachis (@alinabuzachis)" notes: - - Support for I(tags) and I(purge_tags) was added in release 2.0.0. - - In release 5.0.0 the I(s3_url) parameter was merged into the I(endpoint_url) parameter, - I(s3_url) remains as an alias for I(endpoint_url). - - For Walrus I(endpoint_url) should be set to the FQDN of the endpoint with neither scheme nor path. - - Support for the C(S3_URL) environment variable has been - deprecated and will be removed in a release after 2024-12-01, please use the I(endpoint_url) parameter - or the C(AWS_URL) environment variable. + - Support for O(tags) and O(purge_tags) was added in release 2.0.0. + - In release 5.0.0 the O(s3_url) parameter was merged into the O(endpoint_url) parameter, + I(s3_url) remains as an alias for O(endpoint_url). + - For Walrus O(endpoint_url) should be set to the FQDN of the endpoint with neither scheme nor path. + - Support for the E(S3_URL) environment variable has been + deprecated and will be removed in a release after 2024-12-01, please use the O(endpoint_url) parameter + or the E(AWS_URL) environment variable. - Support for creating and deleting buckets was removed in release 6.0.0. extends_documentation_fragment: - amazon.aws.common.modules diff --git a/plugins/modules/s3_object_info.py b/plugins/modules/s3_object_info.py index 39f0c279882..0eff8381199 100644 --- a/plugins/modules/s3_object_info.py +++ b/plugins/modules/s3_object_info.py @@ -12,7 +12,7 @@ description: - Describes objects in S3. - Compatible with AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID (only supports list_keys currently). - - When using non-AWS services, I(endpoint_url) should be specified. + - When using non-AWS services, O(endpoint_url) should be specified. author: - Mandar Vijay Kulkarni (@mandar242) options: @@ -34,8 +34,8 @@ dualstack: description: - Enables Amazon S3 Dual-Stack Endpoints, allowing S3 communications using both IPv4 and IPv6. - - Support for passing I(dualstack) and I(endpoint_url) at the same time has been deprecated, - the dualstack endpoints are automatically configured using the configured I(region). + - Support for passing O(dualstack) and O(endpoint_url) at the same time has been deprecated, + the dualstack endpoints are automatically configured using the configured O(region). Support will be removed in a release after 2024-12-01. type: bool default: false @@ -44,7 +44,7 @@ - Enable API compatibility with Ceph RGW. - It takes into account the S3 API subset working with Ceph in order to provide the same module behaviour where possible. - - Requires I(endpoint_url) if I(ceph=true). + - Requires O(endpoint_url) if O(ceph=true). aliases: ['rgw'] default: false type: bool @@ -93,14 +93,14 @@ attributes_list: description: - The fields/details that should be returned. - - Required when I(object_attributes) is C(true) in I(object_details). + - Required when O(object_details.object_attributes=true). type: list elements: str choices: ['ETag', 'Checksum', 'ObjectParts', 'StorageClass', 'ObjectSize'] notes: - - Support for the C(S3_URL) environment variable has been - deprecated and will be removed in a release after 2024-12-01, please use the I(endpoint_url) parameter - or the C(AWS_URL) environment variable. + - Support for the E(S3_URL) environment variable has been + deprecated and will be removed in a release after 2024-12-01, please use the O(endpoint_url) parameter + or the E(AWS_URL) environment variable. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -153,7 +153,7 @@ RETURN = r""" s3_keys: description: List of object keys. - returned: when only I(bucket_name) is specified and I(object_name), I(object_details) are not specified. + returned: when only O(bucket_name) is specified and O(object_name), O(object_details) are not specified. type: list elements: str sample: @@ -162,13 +162,13 @@ - prefix1/key2 object_info: description: S3 object details. - returned: when I(bucket_name) and I(object_name) are specified. + returned: when O(bucket_name) and O(object_name) are specified. type: list elements: dict contains: object_data: description: A dict containing the metadata of S3 object. - returned: when I(bucket_name) and I(object_name) are specified but I(object_details) is not specified. + returned: when O(bucket_name) and O(object_name) are specified but O(object_details) is not specified. type: dict elements: str contains: @@ -206,7 +206,7 @@ type: int object_acl: description: Access control list (ACL) of an object. - returned: when I(object_acl) is set to I(true). + returned: when O(object_details.object_acl=true). type: complex contains: owner: @@ -251,7 +251,7 @@ sample: "FULL CONTROL" object_legal_hold: description: Object's current legal hold status - returned: when I(object_legal_hold) is set to I(true) and object legal hold is set on the bucket. + returned: when O(object_details.object_legal_hold=true) and object legal hold is set on the bucket. type: complex contains: legal_hold: @@ -266,7 +266,7 @@ sample: "ON" object_lock_configuration: description: Object Lock configuration for a bucket. - returned: when I(object_lock_configuration) is set to I(true) and object lock configuration is set on the bucket. + returned: when O(object_details.object_lock_configuration=true) and object lock configuration is set on the bucket. type: complex contains: object_lock_enabled: @@ -299,7 +299,7 @@ type: int object_retention: description: Object's retention settings. - returned: when I(object_retention) is set to I(true) and object retention is set on the bucket. + returned: when O(object_details.object_retention=true) and object retention is set on the bucket. type: complex contains: retention: @@ -317,11 +317,11 @@ type: str object_tagging: description: The tag-set of an object - returned: when I(object_tagging) is set to I(true). + returned: when O(object_details.object_tagging=true). type: dict object_attributes: description: Object attributes. - returned: when I(object_attributes) is set to I(true). + returned: when O(object_details.object_attributes=true). type: complex contains: etag: diff --git a/plugins/modules/sts_assume_role.py b/plugins/modules/sts_assume_role.py index 9b5f7418e08..a17c06695b5 100644 --- a/plugins/modules/sts_assume_role.py +++ b/plugins/modules/sts_assume_role.py @@ -35,7 +35,7 @@ description: - The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) to 43200 seconds (12 hours). - The max depends on the IAM role's sessions duration setting. - - By default, the value is set to 3600 seconds. + - By default, the value is set to V(3600) seconds. type: int external_id: description: @@ -50,8 +50,8 @@ - The value provided by the MFA device, if the trust policy of the role being assumed requires MFA. type: str notes: - - In order to use the assumed role in a following playbook task you must pass the I(access_key), - I(secret_key) and I(session_token) parameters to modules that should use the assumed credentials. + - In order to use the assumed role in a following playbook task you must pass the O(access_key), + O(secret_key) and O(session_token) parameters to modules that should use the assumed credentials. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -60,7 +60,7 @@ RETURN = r""" sts_creds: - description: The temporary security credentials, which include an access key ID, a secret access key, and a security (or session) token + description: The temporary security credentials, which include an access key ID, a secret access key, and a security (or session) token. returned: always type: dict sample: @@ -69,14 +69,14 @@ secret_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX session_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX sts_user: - description: The Amazon Resource Name (ARN) and the assumed role ID + description: The Amazon Resource Name (ARN) and the assumed role ID. returned: always type: dict sample: assumed_role_id: arn:aws:sts::123456789012:assumed-role/demo/Bob arn: ARO123EXAMPLE123:Bob changed: - description: True if obtaining the credentials succeeds + description: True if obtaining the credentials succeeds. type: bool returned: always """