Guide: Managing S3 Buckets
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides a technical overview of the aws_s3_bucket resource within the Terraform AWS provider. It covers the resource's schema, lifecycle (create, read, update, delete), and key configuration aspects based on its implementation in the provider's source code. The aws_s3_bucket resource is responsible for the full lifecycle management of an AWS S3 bucket.
Many bucket-level configurations like ACLs, policies, and lifecycle rules are defined as separate resources (e.g., aws_s3_bucket_acl, aws_s3_bucket_policy). The core aws_s3_bucket resource schema contains many deprecated, computed-only attributes for these configurations to maintain backward compatibility and to read values configured outside of Terraform.
Sources: internal/service/s3/bucket.go:40-42, internal/service/s3/bucket.go:102-105
Resource Schema
The aws_s3_bucket resource is defined in internal/service/s3/bucket.go. It exposes numerous attributes for configuring and identifying an S3 bucket.
Sources: internal/service/s3/bucket.go:40-621
Key Arguments
| Argument | Type | Description |
|---|---|---|
bucket | TypeString | The name of the bucket. Conflicts with bucket_prefix. If not provided, a unique name is generated. |
bucket_prefix | TypeString | Creates a unique bucket name beginning with the specified prefix. Conflicts with bucket. |
force_destroy | TypeBool | A boolean that indicates all objects should be deleted from the bucket so that the bucket can be destroyed without error. Defaults to false. |
object_lock_configuration | TypeList | A configuration block for S3 Object Lock. Can only be enabled upon creation. |
tags | TypeMap | A map of tags to assign to the bucket. |
Sources: internal/service/s3/bucket.go:47-60, internal/service/s3/bucket.go:420-424, internal/service/s3/bucket.go:565-571, internal/service/s3/bucket.go:618-619
Computed Attributes
| Attribute | Type | Description |
|---|---|---|
arn | TypeString | The ARN of the bucket. |
bucket_domain_name | TypeString | The bucket domain name. |
bucket_regional_domain_name | TypeString | The bucket region-specific domain name. |
hosted_zone_id | TypeString | The Route 53 Hosted Zone ID for this bucket's region. |
region | TypeString | The AWS region this bucket resides in. |
Sources: internal/service/s3/bucket.go:65-80, internal/service/s3/bucket.go:215-222
Deprecated Attributes
The schema includes a large number of deprecated attributes for configurations that have been moved to separate, dedicated resources (e.g., aws_s3_bucket_policy, aws_s3_bucket_lifecycle_configuration). These attributes are now computed-only to read existing configurations but should not be used for new management.
Examples include: acl, policy, cors_rule, website, versioning, logging, lifecycle_rule, replication_configuration, and server_side_encryption_configuration.
Sources: internal/service/s3/bucket.go:87-563
Resource Lifecycle
The resource implements standard CRUD operations to manage the S3 bucket's lifecycle.
Creation (resourceBucketCreate)
The creation process involves generating a bucket name, constructing a CreateBucketInput, and calling the S3 CreateBucket API.
This diagram illustrates the logic flow for creating an S3 bucket.
Sources: internal/service/s3/bucket.go:624-686
Read (resourceBucketRead)
The read operation is responsible for synchronizing the Terraform state with the actual state of the S3 bucket in AWS. It performs a HeadBucket call to verify existence and then a series of Get* calls to fetch various configurations.
This sequence diagram shows the series of API calls made during a read operation to populate the resource's state.
Sources: internal/service/s3/bucket.go:709-1002
Update (resourceBucketUpdate)
The update function primarily handles changes to tags and object lock configuration. Most other bucket properties are managed by separate resources or are ForceNew.
- Tags: If
tags_allhas changed, it callsBucketUpdateTagsto apply the new set of tags to the bucket. - Object Lock: If
object_lock_configurationhas changed, it callsresourceBucketInternalObjectLockConfigurationUpdate, which uses thePutObjectLockConfigurationAPI. Note that object lock can only be enabled at creation and its configuration cannot be removed, only updated.
Sources: internal/service/s3/bucket.go:688-707, internal/service/s3/bucket.go:1614-1628
Deletion (resourceBucketDelete)
The deletion process handles the removal of the S3 bucket. It has special logic for the force_destroy attribute.
This diagram shows the deletion logic, including the handling of non-empty buckets with force_destroy.
Sources: internal/service/s3/bucket.go:1004-1042
Key Bucket Configurations
Object Lock
S3 Object Lock can only be enabled when a bucket is first created. This is handled by checking the object_lock_configuration block during the resourceBucketCreate function.
- The
expandS3ObjectLockConfigurationfunction translates the Terraform configuration into thes3.ObjectLockConfigurationstruct. - If
object_lock_enabledis set toEnabled, theCreateBucketInput.ObjectLockEnabledForBucketfield is set totrue. - Subsequent changes to the retention rule are handled in
resourceBucketUpdateviaPutObjectLockConfiguration.
The use of object lock is demonstrated in tests, which configure a bucket with object_lock_configuration and then manage objects with retention settings.
Sources: internal/service/s3/bucket.go:650-653, internal/service/s3/bucket.go:1708-1720, internal/service/s3/bucket_object_test.go:1003-1025
Lifecycle Rules
Lifecycle rules are read from the GetBucketLifecycleConfiguration API call and flattened into the lifecycle_rule schema attribute. The flattenBucketLifecycleRules function iterates through the rules from the API response and maps them to the schema structure.
The structure of a lifecycle rule includes an ID, status, filter (prefix/tags), and actions like transitions, expirations, and aborting incomplete multipart uploads.
This diagram shows the nested structure of a lifecycle_rule as defined in the schema.
Sources: internal/service/s3/bucket.go:1229-1301
Website Configuration
Static website hosting configuration is read via GetBucketWebsite and flattened by flattenBucketWebsite. It handles properties like index_document, error_document, and redirect_all_requests_to. The website_endpoint and website_domain are computed attributes derived from the bucket's region and name. The logic for determining the correct endpoint URL format is handled in WebsiteDomainUrl, which accounts for older region-specific formats.
Test configurations show how a bucket is configured for website hosting and then referenced by the aws_s3_bucket data source to retrieve the website_endpoint.
Sources: internal/service/s3/bucket.go:802-828, internal/service/s3/bucket.go:1468-1518, internal/service/s3/bucket_data_source_test.go:49-65
Conclusion
The aws_s3_bucket resource provides the foundational block for managing S3 buckets in Terraform. While it centralizes creation, deletion, and core properties like naming and tagging, much of its advanced configuration has been delegated to more specific resources (e.g., aws_s3_bucket_policy, aws_s3_bucket_lifecycle_configuration). The resource's read operation is comprehensive, ensuring that configurations made outside of the main resource are still visible in the Terraform state, which is crucial for backward compatibility and interoperability. The implementation includes robust retry logic and careful handling of S3's eventual consistency model.