amazon.cloud.s3_bucket module – Create and manage S3 buckets

Note

This module is part of the amazon.cloud collection (version 0.4.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install amazon.cloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: amazon.cloud.s3_bucket.

New in amazon.cloud 0.1.0

Synopsis

  • Create and manage S3 buckets.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 3.9

  • boto3 >= 1.25.0

  • botocore >= 1.28.0

  • jsonpatch

Parameters

Parameter

Comments

accelerate_configuration

dictionary

Configuration for the transfer acceleration state.

acceleration_status

string

Configures the transfer acceleration state for an Amazon S3 bucket.

Choices:

  • "Enabled"

  • "Suspended"

access_control

string

A canned access control list (ACL) that grants predefined permissions to the bucket.

Choices:

  • "AuthenticatedRead"

  • "AwsExecRead"

  • "BucketOwnerFullControl"

  • "BucketOwnerRead"

  • "LogDeliveryWrite"

  • "Private"

  • "PublicRead"

  • "PublicReadWrite"

access_key

aliases: aws_access_key_id, aws_access_key, ec2_access_key

string

AWS access key ID.

See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys.

The AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variables may also be used in decreasing order of preference.

The aws_access_key and profile options are mutually exclusive.

The aws_access_key_id alias was added in release 5.1.0 for consistency with the AWS botocore SDK.

The ec2_access_key alias has been deprecated and will be removed in a release after 2024-12-01.

Support for the EC2_ACCESS_KEY environment variable has been deprecated and will be removed in a release after 2024-12-01.

analytics_configurations

list / elements=dictionary

Specifies the configuration and any analyses for the analytics filter of an Amazon S3 bucket.

id

string

The ID that identifies the analytics configuration.

prefix

string

The prefix that an object must have to be included in the analytics results.

storage_class_analysis

dictionary

Specifies data related to access patterns to be collected and made available to analyze the tradeoffs between different storage classes for an Amazon S3 bucket.

data_export

dictionary

Specifies how data related to the storage class analysis for an Amazon S3 bucket should be exported.

destination

dictionary

Specifies information about where to publish analysis or configuration results for an Amazon S3 bucket and S3 Replication Time Control (S3 RTC).

bucket_account_id

string

The account ID that owns the destination S3 bucket.

bucket_arn

string

The Amazon Resource Name (ARN) of the bucket to which data is exported.

format

string

Specifies the file format used when exporting data to Amazon S3.

Choices:

  • "CSV"

  • "ORC"

  • "Parquet"

prefix

string

The prefix to use when exporting data.

The prefix is prepended to all results.

output_schema_version

string

The version of the output schema to use when exporting data.

Default: "V_1"

tag_filters

list / elements=dictionary

Tags to use to identify a subset of objects for an Amazon S3 bucket.

key

string

Not Provived.

value

string

Not Provived.

aws_ca_bundle

path

The location of a CA Bundle to use when validating SSL certificates.

The AWS_CA_BUNDLE environment variable may also be used.

aws_config

dictionary

A dictionary to modify the botocore configuration.

Parameters can be found in the AWS documentation https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config.

bucket_encryption

dictionary

Specifies default encryption for a bucket using server-side encryption with either Amazon S3-managed keys (SSE-S3) or AWS KMS-managed keys (SSE-KMS).

server_side_encryption_configuration

list / elements=dictionary

Specifies the default server-side encryption configuration.

bucket_key_enabled

boolean

Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket.

Existing objects are not affected.

Setting the bucket_key_enabled element to true causes Amazon S3 to use an S3 Bucket Key.

By default, S3 Bucket Key is not enabled.

Choices:

  • false

  • true

server_side_encryption_by_default

dictionary

Specifies the default server-side encryption to apply to new objects in the bucket.

If a PUT Object request doesnt specify any server-side encryption, this default encryption will be applied.

kms_master_key_id

string

KMSMasterKeyID can only be used when you set the value of sse_algorithm as aws:kms.

sse_algorithm

string

Not Provived.

Choices:

  • "AES256"

  • "aws:kms"

bucket_name

string

A name for the bucket.

If you dont specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the bucket name.

cors_configuration

dictionary

Rules that define cross-origin resource sharing of objects in this bucket.

cors_rules

list / elements=dictionary

A set of origins and methods (cross-origin access that you want to allow).

You can add up to 100 rules to the configuration.

allowed_headers

list / elements=string

Headers that are specified in the Access-Control-Request-Headers header.

allowed_methods

list / elements=string

An HTTP method that you allow the origin to execute.

Choices:

  • "DELETE"

  • "GET"

  • "HEAD"

  • "POST"

  • "PUT"

allowed_origins

list / elements=string

One or more origins you want customers to be able to access the bucket from.

exposed_headers

list / elements=string

One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).

id

string

A unique identifier for this rule.

max_age

integer

The time in seconds that your browser is to cache the preflight response for the specified resource.

debug_botocore_endpoint_logs

boolean

Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook.

The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.

Choices:

  • false ← (default)

  • true

endpoint_url

aliases: ec2_url, aws_endpoint_url, s3_url

string

URL to connect to instead of the default AWS endpoints. While this can be used to connection to other AWS-compatible services the amazon.aws and community.aws collections are only tested against AWS.

The AWS_URL or EC2_URL environment variables may also be used, in decreasing order of preference.

The ec2_url and s3_url aliases have been deprecated and will be removed in a release after 2024-12-01.

Support for the EC2_URL environment variable has been deprecated and will be removed in a release after 2024-12-01.

force

boolean

Cancel IN_PROGRESS and PENDING resource requestes.

Because you can only perform a single operation on a given resource at a time, there might be cases where you need to cancel the current resource operation to make the resource available so that another operation may be performed on it.

Choices:

  • false ← (default)

  • true

intelligent_tiering_configurations

list / elements=dictionary

Specifies the S3 Intelligent-Tiering configuration for an Amazon S3 bucket.

id

string

The ID used to identify the S3 Intelligent-Tiering configuration.

prefix

string

An object key name prefix that identifies the subset of objects to which the rule applies.

status

string

Specifies the status of the configuration.

Choices:

  • "Disabled"

  • "Enabled"

tag_filters

list / elements=dictionary

Tags to use to identify a subset of objects for an Amazon S3 bucket.

key

string

Not Provived.

value

string

Not Provived.

tierings

list / elements=dictionary

Specifies a list of S3 Intelligent-Tiering storage class tiers in the configuration.

At least one tier must be defined in the list.

At most, you can specify two tiers in the list, one for each available access_tier: ARCHIVE_ACCESS and DEEP_ARCHIVE_ACCESS.

access_tier

string

S3 Intelligent-Tiering access tier.

See Storage class for automatically optimizing frequently and infrequently accessed objects for a list of access tiers in the S3 Intelligent-Tiering storage class.

Choices:

  • "ARCHIVE_ACCESS"

  • "DEEP_ARCHIVE_ACCESS"

days

integer

The number of consecutive days of no access after which an object will be eligible to be transitioned to the corresponding tier.

The minimum number of days specified for Archive Access tier must be at least 90 days and Deep Archive Access tier must be at least 180 days.

The maximum can be up to 2 years (730 days).

inventory_configurations

list / elements=dictionary

The inventory configuration for an Amazon S3 bucket.

destination

dictionary

Specifies information about where to publish analysis or configuration results for an Amazon S3 bucket and S3 Replication Time Control (S3 RTC).

bucket_account_id

string

The account ID that owns the destination S3 bucket.

bucket_arn

string

The Amazon Resource Name (ARN) of the bucket to which data is exported.

format

string

Specifies the file format used when exporting data to Amazon S3.

Choices:

  • "CSV"

  • "ORC"

  • "Parquet"

prefix

string

The prefix to use when exporting data.

The prefix is prepended to all results.

enabled

boolean

Specifies whether the inventory is enabled or disabled.

Choices:

  • false

  • true

id

string

The ID used to identify the inventory configuration.

included_object_versions

string

Object versions to include in the inventory list.

Choices:

  • "All"

  • "Current"

optional_fields

list / elements=string

Contains the optional fields that are included in the inventory results.

Choices:

  • "BucketKeyStatus"

  • "ETag"

  • "EncryptionStatus"

  • "IntelligentTieringAccessTier"

  • "IsMultipartUploaded"

  • "LastModifiedDate"

  • "ObjectLockLegalHoldStatus"

  • "ObjectLockMode"

  • "ObjectLockRetainUntilDate"

  • "ReplicationStatus"

  • "Size"

  • "StorageClass"

prefix

string

The prefix that is prepended to all inventory results.

schedule_frequency

string

Specifies the schedule for generating inventory results.

Choices:

  • "Daily"

  • "Weekly"

lifecycle_configuration

dictionary

Rules that define how Amazon S3 manages objects during their lifetime.

rules

list / elements=dictionary

You must specify at least one of the following properties: abort_incomplete_multipart_upload, expiration_date, expiration_in_days, noncurrent_version_expiration_in_days, noncurrent_version_transition, noncurrent_version_transitions, transition, or transitions.

abort_incomplete_multipart_upload

dictionary

Specifies the days since the initiation of an incomplete multipart upload that Amazon S3 will wait before permanently removing all parts of the upload.

days_after_initiation

integer

Specifies the number of days after which Amazon S3 aborts an incomplete multipart upload.

expiration_date

string

The date value in ISO 8601 format.

The timezone is always UTC. (YYYY-MM-DDThh:mm:ssZ).

expiration_in_days

integer

Not Provived.

expired_object_delete_marker

boolean

Not Provived.

Choices:

  • false

  • true

id

string

Not Provived.

noncurrent_version_expiration

dictionary

Container for the expiration rule that describes when noncurrent objects are expired.

If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 expire noncurrent object versions at a specific period in the objects lifetime.

newer_noncurrent_versions

integer

Specified the number of newer noncurrent and current versions that must exists before performing the associated action.

noncurrent_days

integer

Specified the number of days an object is noncurrent before Amazon S3 can perform the associated action.

noncurrent_version_expiration_in_days

integer

Not Provived.

noncurrent_version_transition

dictionary

Container for the transition rule that describes when noncurrent objects transition to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER_IR, GLACIER, or DEEP_ARCHIVE storage class.

If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 transition noncurrent object versions to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER_IR, GLACIER, or DEEP_ARCHIVE storage class at a specific period in the objects lifetime.

newer_noncurrent_versions

integer

Specified the number of newer noncurrent and current versions that must exists before performing the associated action.

storage_class

string

The class of storage used to store the object.

Choices:

  • "DEEP_ARCHIVE"

  • "GLACIER"

  • "GLACIER_IR"

  • "Glacier"

  • "INTELLIGENT_TIERING"

  • "ONEZONE_IA"

  • "STANDARD_IA"

transition_in_days

integer

Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action.

noncurrent_version_transitions

list / elements=dictionary

Container for the transition rule that describes when noncurrent objects transition to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER_IR, GLACIER, or DEEP_ARCHIVE storage class.

If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 transition noncurrent object versions to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER_IR, GLACIER, or DEEP_ARCHIVE storage class at a specific period in the objects lifetime.

newer_noncurrent_versions

integer

Specified the number of newer noncurrent and current versions that must exists before performing the associated action.

storage_class

string

The class of storage used to store the object.

Choices:

  • "DEEP_ARCHIVE"

  • "GLACIER"

  • "GLACIER_IR"

  • "Glacier"

  • "INTELLIGENT_TIERING"

  • "ONEZONE_IA"

  • "STANDARD_IA"

transition_in_days

integer

Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action.

object_size_greater_than

string

Not Provived.

object_size_less_than

string

Not Provived.

prefix

string

Not Provived.

status

string

Not Provived.

Choices:

  • "Disabled"

  • "Enabled"

tag_filters

list / elements=dictionary

Tags to use to identify a subset of objects for an Amazon S3 bucket.

key

string

Not Provived.

value

string

Not Provived.

transition

dictionary

You must specify at least one of transition_date and transition_in_days.

storage_class

string

Not Provived.

Choices:

  • "DEEP_ARCHIVE"

  • "GLACIER"

  • "GLACIER_IR"

  • "Glacier"

  • "INTELLIGENT_TIERING"

  • "ONEZONE_IA"

  • "STANDARD_IA"

transition_date

string

The date value in ISO 8601 format.

The timezone is always UTC. (YYYY-MM-DDThh:mm:ssZ).

transition_in_days

integer

Not Provived.

transitions

list / elements=dictionary

You must specify at least one of transition_date and transition_in_days.

storage_class

string

Not Provived.

Choices:

  • "DEEP_ARCHIVE"

  • "GLACIER"

  • "GLACIER_IR"

  • "Glacier"

  • "INTELLIGENT_TIERING"

  • "ONEZONE_IA"

  • "STANDARD_IA"

transition_date

string

The date value in ISO 8601 format.

The timezone is always UTC. (YYYY-MM-DDThh:mm:ssZ).

transition_in_days

integer

Not Provived.

logging_configuration

dictionary

Settings that define where logs are stored.

destination_bucket_name

string

The name of an Amazon S3 bucket where Amazon S3 store server access log files.

You can store log files in any bucket that you own.

By default, logs are stored in the bucket where the logging_configuration property is defined.

log_file_prefix

string

Not Provived.

metrics_configurations

list / elements=dictionary

Settings that define a metrics configuration for the CloudWatch request metrics from the bucket.

access_point_arn

string

Not Provived.

id

string

Not Provived.

prefix

string

Not Provived.

tag_filters

list / elements=dictionary

Tags to use to identify a subset of objects for an Amazon S3 bucket.

key

string

Not Provived.

value

string

Not Provived.

notification_configuration

dictionary

Configuration that defines how Amazon S3 handles bucket notifications.Describes the notification configuration for an Amazon S3 bucket.

event_bridge_configuration

dictionary

Describes the Amazon EventBridge notification configuration for an Amazon S3 bucket.

event_bridge_enabled

boolean

Specifies whether to send notifications to Amazon EventBridge when events occur in an Amazon S3 bucket.

Choices:

  • false

  • true ← (default)

lambda_configurations

list / elements=dictionary

Describes the AWS Lambda functions to invoke and the events for which to invoke them.

event

string

The Amazon S3 bucket event for which to invoke the AWS Lambda function.

filter

dictionary

The filtering rules that determine which objects invoke the AWS Lambda function.Specifies object key name filtering rules.

s3_key

dictionary

A container for object key name prefix and suffix filtering rules.

rules

list / elements=dictionary

Specifies the Amazon S3 object key name to filter on and whether to filter on the suffix or prefix of the key name.

name

string

Not Provived.

value

string

Not Provived.

function

string

The Amazon Resource Name (ARN) of the AWS Lambda function that Amazon S3 invokes when the specified event type occurs.

queue_configurations

list / elements=dictionary

The Amazon Simple Queue Service queues to publish messages to and the events for which to publish messages.

event

string

The Amazon S3 bucket event about which you want to publish messages to Amazon SQS.

filter

dictionary

The filtering rules that determine which objects trigger notifications.

s3_key

dictionary

A container for object key name prefix and suffix filtering rules.

rules

list / elements=dictionary

Specifies the Amazon S3 object key name to filter on and whether to filter on the suffix or prefix of the key name.

name

string

Not Provived.

value

string

Not Provived.

queue

string

The Amazon Resource Name (ARN) of the Amazon SQS queue to which Amazon S3 publishes a message when it detects events of the specified type.

topic_configurations

list / elements=dictionary

The topic to which notifications are sent and the events for which notifications are generated.

event

string

The Amazon S3 bucket event about which to send notifications.

filter

dictionary

The filtering rules that determine for which objects to send notifications.

s3_key

dictionary

A container for object key name prefix and suffix filtering rules.

rules

list / elements=dictionary

Specifies the Amazon S3 object key name to filter on and whether to filter on the suffix or prefix of the key name.

name

string

Not Provived.

value

string

Not Provived.

topic

string

The Amazon Resource Name (ARN) of the Amazon SNS topic to which Amazon S3 publishes a message when it detects events of the specified type.

object_lock_configuration

dictionary

Places an Object Lock configuration on the specified bucket.

object_lock_enabled

string

Not Provived.

Default: "Enabled"

rule

dictionary

The Object Lock rule in place for the specified object.

default_retention

dictionary

The default retention period that you want to apply to new objects placed in the specified bucket.

days

integer

Not Provived.

mode

string

Not Provived.

Choices:

  • "COMPLIANCE"

  • "GOVERNANCE"

years

integer

Not Provived.

object_lock_enabled

boolean

Indicates whether this bucket has an Object Lock configuration enabled.

Choices:

  • false

  • true

ownership_controls

dictionary

Specifies the container element for object ownership rules.

rules

list / elements=dictionary

Not Provived.

object_ownership

string

Specifies an object ownership rule.

Choices:

  • "BucketOwnerEnforced"

  • "BucketOwnerPreferred"

  • "ObjectWriter"

profile

aliases: aws_profile

string

A named AWS profile to use for authentication.

See the AWS documentation for more information about named profiles https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html.

The AWS_PROFILE environment variable may also be used.

The profile option is mutually exclusive with the aws_access_key, aws_secret_key and security_token options.

public_access_block_configuration

dictionary

Configuration that defines how Amazon S3 handles public access.

block_public_acls

boolean

Specifies whether Amazon S3 should block public access control lists (ACLs) for this bucket and objects in this bucket.

Setting this element to True causes the following behavior:.

  • PUT Bucket acl and PUT Object acl calls fail if the specified ACL is public.

  • PUT Object calls fail if the request includes a public ACL.

Enabling this setting doesnt affect existing policies or ACLs.

Choices:

  • false

  • true

block_public_policy

boolean

Specifies whether Amazon S3 should block public bucket policies for this bucket.

Setting this element to True causes Amazon S3 to reject calls to PUT Bucket policy if the specified bucket policy allows public access.

Enabling this setting doesnt affect existing bucket policies.

Choices:

  • false

  • true

ignore_public_acls

boolean

Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket.

Setting this element to True causes Amazon S3 to ignore all public ACLs on this bucket and objects in this bucket.

Enabling this setting doesnt affect the persistence of any existing ACLs and doesnt prevent new public ACLs from being set.

Choices:

  • false

  • true

restrict_public_buckets

boolean

Specifies whether Amazon S3 should restrict public bucket policies for this bucket.

Setting this element to True restricts access to this bucket to only AWS services and authorized users within this account if the bucket has a public policy.

Enabling this setting doesnt affect previously stored bucket policies, except that public and cross-account access within any public bucket policy, including non-public delegation to specific accounts, is blocked.

Choices:

  • false

  • true

purge_tags

boolean

Remove tags not listed in tags.

Choices:

  • false

  • true ← (default)

region

aliases: aws_region, ec2_region

string

The AWS region to use.

For global services such as IAM, Route53 and CloudFront, region is ignored.

The AWS_REGION or EC2_REGION environment variables may also be used.

See the Amazon AWS documentation for more information http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region.

The ec2_region alias has been deprecated and will be removed in a release after 2024-12-01

Support for the EC2_REGION environment variable has been deprecated and will be removed in a release after 2024-12-01.

replication_configuration

dictionary

Configuration for replicating objects in an S3 bucket.A container for replication rules.

You can add up to 1,000 rules.

The maximum size of a replication configuration is 2 MB.

role

string

The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that Amazon S3 assumes when replicating objects.

rules

list / elements=dictionary

Specifies which Amazon S3 objects to replicate and where to store the replicas.

delete_marker_replication

dictionary

Not Provived.

status

string

Not Provived.

Choices:

  • "Disabled"

  • "Enabled"

destination

dictionary

Specifies which Amazon S3 bucket to store replicated objects in and their storage class.

access_control_translation

dictionary

Specify this only in a cross-account scenario (where source and destination bucket owners are not the same), and you want to change replica ownership to the AWS account that owns the destination bucket.

If this is not specified in the replication configuration, the replicas are owned by same AWS account that owns the source object.

owner

string

Not Provived.

Default: "Destination"

account

string

Not Provived.

bucket

string

Not Provived.

encryption_configuration

dictionary

Specifies encryption-related information for an Amazon S3 bucket that is a destination for replicated objects.

replica_kms_key_id

string

Specifies the ID (Key ARN or Alias ARN) of the customer managed customer master key (CMK) stored in AWS Key Management Service (KMS) for the destination bucket.

metrics

dictionary

Not Provived.

event_threshold

dictionary

Not Provived.

minutes

integer

Not Provived.

status

string

Not Provived.

Choices:

  • "Disabled"

  • "Enabled"

replication_time

dictionary

Not Provived.

status

string

Not Provived.

Choices:

  • "Disabled"

  • "Enabled"

time

dictionary

Not Provived.

minutes

integer

Not Provived.

storage_class

string

The storage class to use when replicating objects, such as S3 Standard or reduced redundancy.

Choices:

  • "DEEP_ARCHIVE"

  • "GLACIER"

  • "GLACIER_IR"

  • "INTELLIGENT_TIERING"

  • "ONEZONE_IA"

  • "REDUCED_REDUNDANCY"

  • "STANDARD"

  • "STANDARD_IA"

filter

dictionary

Not Provived.

and

dictionary

Not Provived.

prefix

string

Not Provived.

tag_filters

list / elements=dictionary

Tags to use to identify a subset of objects for an Amazon S3 bucket.

key

string

Not Provived.

value

string

Not Provived.

prefix

string

Not Provived.

tag_filter

dictionary

Tags to use to identify a subset of objects for an Amazon S3 bucket.

key

string

Not Provived.

value

string

Not Provived.

id

string

A unique identifier for the rule.

prefix

string

An object key name prefix that identifies the object or objects to which the rule applies.

priority

integer

Not Provived.

source_selection_criteria

dictionary

A container that describes additional filters for identifying the source objects that you want to replicate.

replica_modifications

dictionary

A filter that you can specify for selection for modifications on replicas.

status

string

Specifies whether Amazon S3 replicates modifications on replicas.

Choices:

  • "Disabled"

  • "Enabled"

sse_kms_encrypted_objects

dictionary

A container for filter information for the selection of Amazon S3 objects encrypted with AWS KMS.A container for filter information for the selection of S3 objects encrypted with AWS KMS.

status

string

Specifies whether Amazon S3 replicates objects created with server-side encryption using a customer master key (CMK) stored in AWS Key Management Service.

Choices:

  • "Disabled"

  • "Enabled"

status

string

Specifies whether the rule is enabled.

Choices:

  • "Disabled"

  • "Enabled"

secret_key

aliases: aws_secret_access_key, aws_secret_key, ec2_secret_key

string

AWS secret access key.

See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys.

The AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variables may also be used in decreasing order of preference.

The secret_key and profile options are mutually exclusive.

The aws_secret_access_key alias was added in release 5.1.0 for consistency with the AWS botocore SDK.

The ec2_secret_key alias has been deprecated and will be removed in a release after 2024-12-01.

Support for the EC2_SECRET_KEY environment variable has been deprecated and will be removed in a release after 2024-12-01.

session_token

aliases: aws_session_token, security_token, aws_security_token, access_token

string

AWS STS session token for use with temporary credentials.

See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys.

The AWS_SESSION_TOKEN, AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variables may also be used in decreasing order of preference.

The security_token and profile options are mutually exclusive.

Aliases aws_session_token and session_token were added in release 3.2.0, with the parameter being renamed from security_token to session_token in release 6.0.0.

The security_token, aws_security_token, and access_token aliases have been deprecated and will be removed in a release after 2024-12-01.

Support for the EC2_SECRET_KEY and AWS_SECURITY_TOKEN environment variables has been deprecated and will be removed in a release after 2024-12-01.

state

string

Goal state for resource.

state=present creates the resource if it doesn’t exist, or updates to the provided state if the resource already exists.

state=absent ensures an existing instance is deleted.

state=list get all the existing resources.

state=describe or state=get retrieves information on an existing resource.

Choices:

  • "present" ← (default)

  • "absent"

  • "list"

  • "describe"

  • "get"

tags

aliases: resource_tags

dictionary

A dict of tags to apply to the resource.

To remove all tags set tags={} and purge_tags=true.

validate_certs

boolean

When set to false, SSL certificates will not be validated for communication with the AWS APIs.

Setting validate_certs=false is strongly discouraged, as an alternative, consider setting aws_ca_bundle instead.

Choices:

  • false

  • true ← (default)

versioning_configuration

dictionary

Describes the versioning state of an Amazon S3 bucket.

status

string

The versioning state of the bucket.

Choices:

  • "Enabled"

  • "Suspended" ← (default)

wait

boolean

Wait for operation to complete before returning.

Choices:

  • false ← (default)

  • true

wait_timeout

integer

How many seconds to wait for an operation to complete before timing out.

Default: 320

website_configuration

dictionary

Specifies website configuration parameters for an Amazon S3 bucket.

error_document

string

The name of the error document for the website.

index_document

string

The name of the index document for the website.

redirect_all_requests_to

dictionary

Specifies the redirect behavior of all requests to a website endpoint of an Amazon S3 bucket.

host_name

string

Name of the host where requests are redirected.

protocol

string

Protocol to use when redirecting requests.

The default is the protocol that is used in the original request.

Choices:

  • "http"

  • "https"

routing_rules

list / elements=dictionary

Specifies the redirect behavior and when a redirect is applied.

redirect_rule

dictionary

Container for redirect information.

You can redirect requests to another host, to another page, or with another protocol.

In the event of an error, you can specify a different error code to return.Specifies how requests are redirected.

In the event of an error, you can specify a different error code to return.

host_name

string

The host name to use in the redirect request.

http_redirect_code

string

The HTTP redirect code to use on the response.

Not required if one of the siblings is present.

protocol

string

Protocol to use when redirecting requests.

The default is the protocol that is used in the original request.

Choices:

  • "http"

  • "https"

replace_key_prefix_with

string

The object key prefix to use in the redirect request.

replace_key_with

string

The specific object key to use in the redirect request.d.

routing_rule_condition

dictionary

A container for describing a condition that must be met for the specified redirect to apply.You must specify at least one of http_error_code_returned_equals and key_prefix_equals.

http_error_code_returned_equals

string

The HTTP error code when the redirect is applied.

key_prefix_equals

string

The object key name prefix when the redirect is applied.

Notes

Note

  • Caution: For modules, environment variables and configuration files are read from the Ansible ‘host’ context and not the ‘controller’ context. As such, files may need to be explicitly copied to the ‘host’. For lookup and connection plugins, environment variables and configuration files are read from the Ansible ‘controller’ context and not the ‘host’ context.

  • The AWS SDK (boto3) that Ansible uses may also read defaults for credentials and other settings, such as the region, from its configuration files in the Ansible ‘host’ context (typically ~/.aws/credentials). See https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html for more information.

Examples

- name: Create S3 bucket
  amazon.cloud.s3_bucket:
    bucket_name: '{{ bucket_name }}'
    state: present
  register: output

- name: Describe S3 bucket
  amazon.cloud.s3_bucket:
    state: describe
    bucket_name: '{{ output.result.identifier }}'
  register: _result

- name: List S3 buckets
  amazon.cloud.s3_bucket:
    state: list
  register: _result

- name: Update S3 bucket public access block configuration and tags (diff=true)
  amazon.cloud.s3_bucket:
    bucket_name: '{{ output.result.identifier }}'
    state: present
    public_access_block_configuration:
      block_public_acls: false
      block_public_policy: false
      ignore_public_acls: false
      restrict_public_buckets: false
    tags:
      mykey: myval
  diff: true
  register: _result

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

result

complex

When state=list, it is a list containing dictionaries of resource information.

Otherwise, it is a dictionary of resource information.

When state=absent, it is an empty dictionary.

Returned: always

identifier

string

The unique identifier of the resource.

Returned: success

properties

dictionary

The resource properties.

Returned: success

Authors

  • Ansible Cloud Team (@ansible-collections)