The terraform-aws-s3-bucket module represents a centralized Terraform construct for creating and managing AWS S3 buckets with extensive configuration coverage. The module abstracts the complexity of S3 bucket management while providing fine-grained control over bucket properties, security settings, and integration with other AWS services. The module is designed to be comprehensive, handling nearly all S3 bucket configurations supported by the AWS provider for Terraform. The module is organized around several core components that work together to provision and configure S3 buckets. The module uses local variables and conditional logic to determine which resources should be created based on the provided configuration. Organizations that adopt the module gain a repeatable pattern for bucket creation that aligns with AWS best practices and reduces configuration drift across environments.
The module creates AWS S3 buckets with comprehensive security, lifecycle, and management features following AWS best practices. Server-side encryption is supported with SSE-S3 or SSE-KMS. Versioning is supported with optional MFA delete. Object Lock configuration is supported. Lifecycle policies with Intelligent-Tiering support are supported. Cross-Region Replication is supported. Access logging is supported. CORS configuration is supported. Event notifications are supported. Bucket metrics and inventory are supported. CloudWatch alarms are supported. Public access blocking is default enabled. Comprehensive tagging is supported. When using this module as a no-code module in HCP Terraform, AWS credentials need to be configured.
Storing Terraform modules in S3 buckets is a practical choice for organizations that are already invested in AWS and want a simple, private module distribution mechanism. You do not need a Terraform Registry or Git server. Just package your module as a zip file, upload it to S3, and reference it in your configuration. AWS IAM handles authentication, and S3 versioning can help protect module objects from accidental overwrites or deletions. This guide covers how to package, upload, and reference S3-hosted modules.
Core Module Capabilities and Feature Coverage
The terraform-aws-s3-bucket module is a comprehensive Terraform solution for creating and managing AWS S3 buckets with an extensive range of configurations and features. The module abstracts the complexity of S3 bucket management while providing fine-grained control over bucket properties, security settings, and integration with other AWS services. This module enables users to provision buckets with a single module invocation while exposing variables for nearly every S3 attribute exposed by the AWS provider.
The module supports a comprehensive set of S3 bucket features. The feature set spans basic configuration, access control, encryption, storage management, website hosting, integrations, monitoring, and security policies.
| Feature Category | Supported Features | Configuration Variable |
|---|---|---|
| Basic Configuration | Bucket creation, naming, force destroy | bucket, bucketprefix, forcedestroy |
| Access Control | ACLs, Object Ownership, Public Access Block | acl, grant, objectownership, blockpublic_acls |
| Encryption | SSE-S3, SSE-KMS, Encryption policies | serversideencryption_configuration |
| Storage Management | Versioning, Lifecycle rules, Intelligent tiering | versioning, lifecyclerule, intelligenttiering |
| Website Hosting | Index/error docs, redirects, routing rules | website |
| Integrations | CORS, Logging, Replication, Notifications | corsrule, logging, replicationconfiguration |
| Monitoring | Metrics, Inventory, Analytics | metricconfiguration, inventoryconfiguration, analytics_configuration |
| Security Policies | TLS |
The table reflects the mapping between high level categories and the variables that control them. The mapping allows operators to locate the correct variable for a desired outcome without scanning the entire module source.
These features of S3 bucket configurations are supported:
- static web-site hosting
- access logging
- versioning
- CORS
- lifecycle rules
- server-side encryption
- object locking
- Cross-Region Replication (CRR)
- ELB log delivery bucket policy
- ALB/NLB log delivery bucket policy
- WAF log delivery bucket policy
- Account-level Public Access Block
- S3 Directory Bucket
- S3 Table Bucket
- S3 Vectors
The breadth of support means the module can be used for data lakes, static site hosting, log aggregation, and specialized S3 features such as Directory Buckets, Table Buckets, and Vectors. The impact for a user is reduced duplication of Terraform code across teams and a consistent security posture by default.
Module Invocation Patterns
The simplest way to use the module is to create a basic S3 bucket. The basic invocation establishes a bucket name and source identifier.
hcl
module "s3_bucket" {
source = "terraform-aws-modules/s3-bucket/aws"
bucket = "my-s3-bucket"
acl = "private"
control_object_ownership = true
object_ownership = "ObjectWriter"
versioning = {
enabled = true
}
}
The source points to terraform-aws-modules/s3-bucket/aws. The bucket argument sets the name. The acl argument sets the access control list to private. The controlobjectownership flag enables explicit ownership control. The object_ownership value ObjectWriter determines who can write objects. The versioning block enables versioning with enabled set to true.
For a more secure configuration with versioning enabled, the controlobjectownership and object_ownership parameters ensure proper object ownership controls, while versioning enables keeping multiple versions of an object. The real-world consequence is protection against accidental overwrites and the ability to restore prior object versions after an error.
A common pattern is log storage. S3 buckets are commonly used for storing logs from various AWS services.
hcl
module "s3_bucket_for_logs" {
source = "terraform-aws-modules/s3-bucket/aws"
bucket = "my-s3-bucket-for-logs"
acl = "log-delivery-write"
force_destroy = true
control_object_ownership = true
object_ownership = "ObjectWriter"
attach_elb_log_delivery_policy = true
}
The bucket is named for logs. The acl is set to log-delivery-write to allow AWS log delivery. forcedestroy is true to allow deletion of non-empty bucket. The object ownership controls are set as before. attachelblogdelivery_policy is true to attach the ELB log delivery bucket policy.
A variant of the log bucket adds both ELB and load balancer log delivery.
hcl
module "s3_bucket_for_logs" {
source = "terraform-aws-modules/s3-bucket/aws"
bucket = "my-s3-bucket-for-logs"
force_destroy = true
control_object_ownership = true
object_ownership = "ObjectWriter"
attach_elb_log_delivery_policy = true
attach_lb_log_delivery_policy = true
}
The attachelblogdeliverypolicy is required for ALB logs. The attachlblogdeliverypolicy is required for ALB/NLB logs. The presence of both flags ensures the bucket can receive logs from multiple load balancing services without manual policy authoring.
The module also supports WAF log delivery.
hcl
module "s3_bucket_for_waf_logs" {
source = "terraform-aws-modules/s3-bucket/aws"
bucket =
}
The partial example signals that a WAF log bucket can be created with the same source. The impact is centralized log retention with correct IAM permissions applied by the module.
S3-Hosted Terraform Module Distribution
Storing Terraform modules in S3 buckets is a practical choice for organizations that are already invested in AWS and want a simple, private module distribution mechanism. You do not need a Terraform Registry or Git server. Just package your module as a zip file, upload it to S3, and reference it in your configuration. AWS IAM handles authentication, and S3 versioning can help protect module objects from accidental overwrites or deletions.
How S3 Module Sources Work
Terraform can download modules from S3 buckets using the s3:: prefix. When it encounters this source, it downloads the archive from S3, extracts it, and uses the contents as the module code.
hcl
module "vpc" {
source = "s3::https://my-terraform-modules.s3.amazonaws.com/vpc/v1.0.0.zip"
vpc_cidr = "10.0.0.0/16"
environment = "production"
}
Terraform expects the S3 object to be a zip archive containing the module's .tf files. The s3:: prefix triggers the download and extraction. The impact for teams is private module distribution without external registries. Authentication is handled through AWS IAM, so access can be restricted to specific roles or accounts.
Packaging a Module for S3
First, you need to create a zip archive of your module. The archive must contain the module's .tf files at the root or in a predictable layout so Terraform can discover them after extraction. S3 versioning can protect module objects from accidental overwrites or deletions. The contextual layer is that S3 versioning provides an audit trail for module changes, which is critical for regulated environments.
Getting Started and Integration Points
This guide provides instructions for quickly getting started with the AWS S3 bucket Terraform module. It covers basic setup, common usage patterns, and essential configurations. For comprehensive feature details, see Features and Capabilities.
Before using this module, ensure you have the prerequisites in place. The module integrates with your Terraform configuration and AWS. The diagram illustrates how the terraform-aws-s3-bucket module integrates with your Terraform configuration and AWS.
The simplest way to use the module is to create a basic S3 bucket. For a more secure configuration with versioning enabled, the controlobjectownership and object_ownership parameters ensure proper object ownership controls, while versioning enables keeping multiple versions of an object.
Secure your S3 bucket with encryption, access controls, and security policies. For more comprehensive security configurations, refer to Security Configurations.
Configure your S3 bucket for static website hosting. The website hosting feature enables index and error documents, redirects, and routing rules.
Configure lifecycle rules to automatically transition or expire objects. Lifecycle rules reduce storage costs by moving objects to cheaper tiers or expiring them after a retention period.
You can conditionally create a bucket using the create_bucket parameter. This is useful when you need to manage bucket creation based on environment variables or other conditions.
You can create multiple similar buckets in two ways:
- for_each meta-argument
Refer to the wrappers directory in the module repository for detailed implementation.
After mastering the basics, you can explore advanced usage scenarios. For advanced usage scenarios, refer to Advanced Usage Patterns.
Storage Management and Lifecycle Controls
Storage Management is covered by versioning, lifecyclerule, and intelligenttiering variables. Versioning with optional MFA delete provides historical retention. Lifecycle rules automate transition and expiration. Intelligent-Tiering support optimizes cost without manual intervention. The impact is lower storage spend and reduced operational overhead for data retention policies.
The module supports Object Lock configuration. Object Lock enables WORM compliance for regulated data. Cross-Region Replication ensures data durability across regions. Access logging provides audit trails for bucket access. Event notifications enable reactive workflows via SNS, SQS, or Lambda.
Security and Access Control
Access Control variables include acl, grant, objectownership, and blockpublic_acls. The module supports Account-level Public Access Block. The module supports Server-side encryption with SSE-S3 or SSE-KMS and encryption policies. Public access blocking is default enabled. The impact is defense in depth against accidental public exposure and compliance with security standards.
The module supports ELB log delivery bucket policy, ALB/NLB log delivery bucket policy, and WAF log delivery bucket policy. Attaching these policies automates the precise permissions required for AWS services to deliver logs. The user avoids manual policy authoring and reduces risk of misconfiguration.
Encryption policies are controlled via serversideencryption_configuration. The real-world consequence is that sensitive data at rest is protected by AWS-managed or customer-managed keys without additional resource definitions.
Website Hosting and Integrations
Website Hosting is controlled via the website variable. Index/error docs, redirects, and routing rules are supported. The module abstracts the complex website configuration for S3 static hosting.
Integrations include CORS via corsrule, Logging via logging, Replication via replicationconfiguration, and Notifications via event notifications. The module enables CORS configuration for browser-based access. Logging configuration enables access logging to a target bucket. Replication configuration enables Cross-Region Replication. Notifications enable integration with other AWS services.
Monitoring includes metricconfiguration, inventoryconfiguration, and analytics_configuration. Bucket metrics and inventory are supported. CloudWatch alarms can be configured. The impact is operational visibility without custom monitoring code.
Conclusion
The terraform-aws-s3-bucket module provides a single source of truth for S3 bucket provisioning across environments. The module abstracts the complexity of S3 bucket management while providing fine-grained control over bucket properties, security settings, and integration with other AWS services. The module is designed to be comprehensive, handling nearly all S3 bucket configurations supported by the AWS provider for Terraform. The module uses local variables and conditional logic to determine which resources should be created based on the provided configuration.
S3-hosted module distribution complements the module by enabling private module delivery without a public registry. Terraform can download modules from S3 buckets using the s3:: prefix. When it encounters this source, it downloads the archive from S3, extracts it, and uses the contents as the module code. AWS IAM handles authentication, and S3 versioning can help protect module objects from accidental overwrites or deletions.
The combined effect is a repeatable, secure, and cost-aware approach to S3 usage. Teams can standardize on the module for bucket creation, enforce security defaults such as public access blocking and encryption, and distribute custom modules privately via S3. The feature coverage spans static website hosting, access logging, versioning, CORS, lifecycle rules, server-side encryption, object locking, Cross-Region Replication, log delivery policies, and advanced S3 types including Directory Bucket, Table Bucket, and Vectors. The module continues to serve as a central abstraction for S3 best practices.