diff --git a/changelogs/fragments/2135-update-retrun-block-s3_bucket-s3_bucket_info-s3_object.yml b/changelogs/fragments/2135-update-retrun-block-s3_bucket-s3_bucket_info-s3_object.yml new file mode 100644 index 00000000000..36aa1b19344 --- /dev/null +++ b/changelogs/fragments/2135-update-retrun-block-s3_bucket-s3_bucket_info-s3_object.yml @@ -0,0 +1,3 @@ +--- +trivial: + - Update return block in the module documentation for s3_bucket, s3_bucket_info, s3_object modules (https://github.com/ansible-collections/amazon.aws/pull/2135). \ No newline at end of file diff --git a/plugins/modules/s3_bucket.py b/plugins/modules/s3_bucket.py index d259286f9c0..b27c3acede7 100644 --- a/plugins/modules/s3_bucket.py +++ b/plugins/modules/s3_bucket.py @@ -290,25 +290,26 @@ RETURN = r""" encryption: - description: - - Server-side encryption of the objects in the S3 bucket. - type: str - returned: I(state=present) - sample: '' + description: Server-side encryption of the objects in the S3 bucket. + type: dict + returned: when O(state=present) + sample: { + "SSEAlgorithm": "AES256" + } name: - description: Name of the S3 bucket. + description: Bucket name. + returned: when O(state=present) type: str - returned: I(state=present) - sample: "2d3ce10a8210d36d6b4d23b822892074complex" + sample: "a-testing-bucket-name" object_ownership: description: S3 bucket's ownership controls. type: str - returned: I(state=present) + returned: when O(state=present) sample: "BucketOwnerPreferred" policy: description: S3 bucket's policy. type: dict - returned: I(state=present) + returned: when O(state=present) sample: { "Statement": [ { @@ -322,15 +323,14 @@ "Version": "2012-10-17" } requester_pays: - description: - - Indicates that the requester was successfully charged for the request. - type: str - returned: I(state=present) - sample: '' + description: Indicates that the requester was successfully charged for the request. + type: bool + returned: when O(state=present) + sample: true tags: description: S3 bucket's tags. type: dict - returned: I(state=present) + returned: when O(state=present) sample: { "Tag1": "tag1", "Tag2": "tag2" @@ -338,16 +338,59 @@ versioning: description: S3 bucket's versioning configuration. type: dict - returned: I(state=present) + returned: when O(state=present) sample: { "MfaDelete": "Disabled", "Versioning": "Enabled" } + contains: + MfaDelete: + description: Specifies whether MFA delete is enabled in the bucket versioning configuration. + returned: when O(state=presnet) and MfaDelete configured on bucket. + type: str + Versioning: + description: The versioning state of the bucket. + type: str + returned: always acl: description: S3 bucket's canned ACL. type: dict - returned: I(state=present) - sample: 'public-read' + returned: when O(state=present). + sample: "public-read" +object_lock_enabled: + description: Whether S3 Object Lock is enabled. + type: bool + returned: when O(state=present) + sample: false +public_access_block: + description: Bucket public access block configuration. + returned: when O(state=present) + type: dict + sample: { + "PublicAccessBlockConfiguration": { + "BlockPublicAcls": true, + "BlockPublicPolicy": true, + "IgnorePublicAcls": true, + "RestrictPublicBuckets": true + } + } + contains: + PublicAccessBlockConfiguration: + description: The PublicAccessBlock configuration currently in effect for this Amazon S3 bucket. + type: dict + contains: + BlockPublicAcls: + description: Specifies whether Amazon S3 should block public access control lists (ACLs) for this bucket and objects in this bucket. + type: bool + BlockPublicPolicy: + description: Specifies whether Amazon S3 should block public bucket policies for this bucket. + type: bool + IgnorePublicAcls: + description: Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket. + type: bool + RestrictPublicBuckets: + description: Specifies whether Amazon S3 should restrict public bucket policies for this bucket. + type: bool """ import json @@ -469,7 +512,6 @@ def handle_bucket_requester_pays(s3_client, module: AnsibleAWSModule, name: str) put_bucket_request_payment(s3_client, name, payer) requester_pays_status = wait_payer_is_applied(module, s3_client, name, payer, should_fail=True) requester_pays_changed = True - return requester_pays_changed, requester_pays diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py index b382e5eebd3..acae57a2826 100644 --- a/plugins/modules/s3_bucket_info.py +++ b/plugins/modules/s3_bucket_info.py @@ -164,16 +164,24 @@ """ RETURN = r""" -bucket_list: - description: "List of buckets" +buckets: + description: A list of S3 buckets. returned: always type: complex contains: + bucket_accelerate_configuration: + description: The accelerate configuration of the bucket. + returned: when O(bucket_facts=true) and RV(buckets.bucket_accelerate_configuration=true). + type: dict + sample: { + 'Status': 'Enabled', + 'RequestCharged': 'requester' + } name: description: Bucket name. returned: always type: str - sample: a-testing-bucket-name + sample: "a-testing-bucket-name" creation_date: description: Bucket creation date timestamp. returned: always @@ -181,8 +189,16 @@ sample: "2021-01-21T12:44:10+00:00" public_access_block: description: Bucket public access block configuration. - returned: when I(bucket_facts=true) and I(public_access_block=true) - type: complex + returned: when O(bucket_facts=true) and RV(buckets.public_access_block=true). + type: dict + sample: { + "PublicAccessBlockConfiguration": { + "BlockPublicAcls": true, + "BlockPublicPolicy": true, + "IgnorePublicAcls": true, + "RestrictPublicBuckets": true + } + } contains: PublicAccessBlockConfiguration: description: PublicAccessBlockConfiguration data. @@ -192,107 +208,165 @@ BlockPublicAcls: description: BlockPublicAcls setting value. type: bool - sample: true BlockPublicPolicy: description: BlockPublicPolicy setting value. type: bool - sample: true IgnorePublicAcls: description: IgnorePublicAcls setting value. type: bool - sample: true RestrictPublicBuckets: description: RestrictPublicBuckets setting value. type: bool - sample: true bucket_name_filter: description: String used to limit buckets. See I(name_filter). - returned: when I(name_filter) is defined + returned: when O(name_filter) is defined type: str - sample: filter-by-this-string + sample: "filter-by-this-string" bucket_acl: description: Bucket ACL configuration. - returned: when I(bucket_facts=true) and I(bucket_acl=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_acl=true). type: complex contains: Grants: description: List of ACL grants. type: list - sample: [] + elements: dict + sample: [ + { + "Grantee": { + "DisplayName": "abc-aws-root+721234567890", + "ID": "1234567890cbc0f1234567890f1234567890c123456789012123456789091234", + "Type": "CanonicalUser" + }, + "Permission": "FULL_CONTROL" + } + ] + contains: + Grantee: + description: The person being granted permissions. + type: dict + contains: + DisplayName: + description: Screen name of the grantee. + type: str + ID: + description: The canonical user ID of the grantee. + type: str + Type: + description: Type of grantee. + type: str + Permission: + description: Specifies the permission given to the grantee. + type: str Owner: description: Bucket owner information. - type: complex + type: dict + sample: { + "DisplayName": "abc-aws-root+721234567890", + "ID": "1234567890cbc0f1234567890f1234567890c123456789012123456789091234" + } contains: DisplayName: description: Bucket owner user display name. - returned: always type: str - sample: username ID: description: Bucket owner user ID. - returned: always type: str - sample: 123894e509349etc bucket_cors: description: Bucket CORS configuration. - returned: when I(bucket_facts=true) and I(bucket_cors=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_cors=true) type: complex contains: CORSRules: description: Bucket CORS configuration. - returned: when CORS rules are defined for the bucket + returned: When CORS rules are defined for the bucket type: list sample: [] bucket_encryption: description: Bucket encryption configuration. - returned: when I(bucket_facts=true) and I(bucket_encryption=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_encryption=true). type: complex + sample: { + "ServerSideEncryptionConfiguration": { + "Rules": [ + { + "ApplyServerSideEncryptionByDefault": { + "SSEAlgorithm": "AES256" + }, + "BucketKeyEnabled": true + } + ] + } + } contains: ServerSideEncryptionConfiguration: description: ServerSideEncryptionConfiguration configuration. - returned: when encryption is enabled on the bucket + returned: when encryption is enabled on the bucket. type: complex contains: Rules: description: List of applied encryptio rules. - returned: when encryption is enabled on the bucket + returned: when encryption is enabled on the bucket. type: list - sample: { "ApplyServerSideEncryptionByDefault": { "SSEAlgorithm": "AES256" }, "BucketKeyEnabled": False } + elements: dict + contains: + ApplyServerSideEncryptionByDefault: + description: Specifies the default server-side encryption to apply to new objects in the bucket. + type: dict + contains: + SSEAlgorithm: + description: Server-side encryption algorithm to use for the default encryption. + type: str + KMSMasterKeyID: + description: Amazon Web Services Key Management Service (KMS) customer Amazon Web Services KMS key ID to use for the default encryption. + type: str + BucketKeyEnabled: + description: + - Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket. + type: bool bucket_lifecycle_configuration: description: Bucket lifecycle configuration settings. - returned: when I(bucket_facts=true) and I(bucket_lifecycle_configuration=true) - type: complex + returned: when O(bucket_facts=true) and RV(buckets.bucket_lifecycle_configuration=true). + type: list + elements: dict contains: Rules: description: List of lifecycle management rules. - returned: when lifecycle configuration is present + returned: when lifecycle configuration is present. type: list - sample: [{ "Status": "Enabled", "ID": "example-rule" }] + sample: [ + { + "Status": "Enabled", + "ID": "example-rule" + } + ] bucket_location: description: Bucket location. - returned: when I(bucket_facts=true) and I(bucket_location=true) - type: complex + returned: when O(bucket_facts=true) and RV(buckets.bucket_location=true). + type: dict + sample: { + "LocationConstraint": "us-east-1" + } contains: LocationConstraint: description: AWS region. returned: always type: str - sample: us-east-2 bucket_logging: description: Server access logging configuration. - returned: when I(bucket_facts=true) and I(bucket_logging=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_logging=true). type: complex contains: LoggingEnabled: description: Server access logging configuration. - returned: when server access logging is defined for the bucket + returned: when server access logging is defined for the bucket. type: complex contains: TargetBucket: description: Target bucket name. returned: always type: str - sample: logging-bucket-name + sample: "logging-bucket-name" TargetPrefix: description: Prefix in target bucket. returned: always @@ -300,117 +374,145 @@ sample: "" bucket_notification_configuration: description: Bucket notification settings. - returned: when I(bucket_facts=true) and I(bucket_notification_configuration=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_notification_configuration=true). type: complex contains: TopicConfigurations: description: List of notification events configurations. - returned: when at least one notification is configured + returned: when at least one notification is configured. type: list - sample: [] + sample: [ + { + 'Id': 'topic-config-dev001', + 'TopicArn': 'arn:aws:sns:us-west-1:721234567890:sns-dev001-topic', + 'Events': [ + "s3:ObjectCreated:Copy" + ], + 'Filter': { + 'Key': { + 'FilterRules': [ + { + "Name": "Prefix", + "Value": "test/" + }, + ] + } + } + }, + ] bucket_ownership_controls: description: Preffered object ownership settings. - returned: when I(bucket_facts=true) and I(bucket_ownership_controls=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_ownership_controls=true) type: complex + sample: { + "OwnershipControls": { + "Rules": [ + { + "ObjectOwnership": "BucketOwnerEnforced" + } + ] + } + } contains: OwnershipControls: description: Object ownership settings. - returned: when ownership controls are defined for the bucket + returned: when ownership controls are defined for the bucket. type: complex contains: Rules: description: List of ownership rules. - returned: when ownership rule is defined + returned: when ownership rule is defined. type: list - sample: [{ "ObjectOwnership:": "ObjectWriter" }] bucket_policy: description: Bucket policy contents. - returned: when I(bucket_facts=true) and I(bucket_policy=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_policy=true). type: str sample: '{"Version":"2012-10-17","Statement":[{"Sid":"AddCannedAcl","Effect":"Allow",..}}]}' bucket_policy_status: description: Status of bucket policy. - returned: when I(bucket_facts=true) and I(bucket_policy_status=true) - type: complex + returned: when O(bucket_facts=true) and RV(buckets.bucket_policy_status=true). + type: dict contains: PolicyStatus: description: Status of bucket policy. - returned: when bucket policy is present - type: complex + returned: when bucket policy is present. + type: dict contains: IsPublic: description: Report bucket policy public status. - returned: when bucket policy is present + returned: when bucket policy is present. type: bool sample: True bucket_replication: description: Replication configuration settings. - returned: when I(bucket_facts=true) and I(bucket_replication=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_replication=true). type: complex contains: Role: description: IAM role used for replication. - returned: when replication rule is defined + returned: when replication rule is defined. type: str sample: "arn:aws:iam::123:role/example-role" Rules: description: List of replication rules. - returned: when replication rule is defined + returned: when replication rule is defined. type: list sample: [{ "ID": "rule-1", "Filter": "{}" }] bucket_request_payment: description: Requester pays setting. - returned: when I(bucket_facts=true) and I(bucket_request_payment=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_request_payment=true) type: complex + sample: { + "Payer": "BucketOwner" + } contains: Payer: description: Current payer. returned: always type: str - sample: BucketOwner bucket_tagging: description: Bucket tags. - returned: when I(bucket_facts=true) and I(bucket_tagging=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_tagging=true). type: dict sample: { "Tag1": "Value1", "Tag2": "Value2" } bucket_website: description: Static website hosting. - returned: when I(bucket_facts=true) and I(bucket_website=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_website=true). type: complex contains: ErrorDocument: description: Object serving as HTTP error page. - returned: when static website hosting is enabled + returned: when static website hosting is enabled. type: dict sample: { "Key": "error.html" } IndexDocument: description: Object serving as HTTP index page. - returned: when static website hosting is enabled + returned: when static website hosting is enabled. type: dict sample: { "Suffix": "error.html" } RedirectAllRequestsTo: description: Website redict settings. - returned: when redirect requests is configured + returned: when redirect requests is configured. type: complex contains: HostName: description: Hostname to redirect. returned: always type: str - sample: www.example.com + sample: "www.example.com" Protocol: description: Protocol used for redirect. returned: always type: str - sample: https + sample: "https" bucket_versioning: description: - The versioning state of the bucket. - This will also specify whether MFA delete is enabled in the bucket versioning configuration. if only the bucket has been configured with MFA delete. - returned: when I(bucket_facts=true) and I(bucket_versioning=true) + returned: when O(bucket_facts=true) and RV(buckets.bucket_versioning=true). type: dict - sample: { 'Status': 'Enabled' } + sample: { "Status": "Enabled" } version_added: 7.2.0 """ diff --git a/plugins/modules/s3_object.py b/plugins/modules/s3_object.py index c3e45004a37..e08903b7ddd 100644 --- a/plugins/modules/s3_object.py +++ b/plugins/modules/s3_object.py @@ -377,12 +377,12 @@ description: Message indicating the status of the operation. returned: always type: str - sample: PUT operation complete + sample: "PUT operation complete" url: 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= + 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. returned: (for geturl operation) @@ -402,6 +402,14 @@ - prefix1/ - prefix1/key1 - prefix1/key2 +tags: + description: Tags of the s3 object. + returned: always + type: dict + sample: { + "Owner": "dev001", + "env": "test" + } """ import base64