Usage

Creates a AWS S3 bucket.

module "s3_bucket" {
  source = "dod-iac/s3-bucket/aws"

  name = format("app-%s-s3-%s", var.application, var.environment)
  tags = {
    Application = var.application
    Environment = var.environment
    Automation  = "Terraform"
  }
}

Creates an encrypted AWS S3 bucket.

module "s3_kms_key" {
  source = "dod-iac/s3-kms-key/aws"

  name = format("alias/app-%s-s3-%s", var.application, var.environment)
  description = format("A KMS key used to encrypt objects at rest in S3 for %s:%s.", var.application, var.environment)
  principals = ["*"]
  tags = {
    Application = var.application
    Environment = var.environment
    Automation  = "Terraform"
  }
}

module "s3_bucket" {
  source = "dod-iac/s3-bucket/aws"

  kms_master_key_id = module.s3_kms_key.aws_kms_key_arn
  name = format("app-%s-s3-%s", var.application, var.environment)
  tags = {
    Application = var.application
    Environment = var.environment
    Automation  = "Terraform"
  }
}

Testing

Run all terratest tests using the terratest script. If using aws-vault, you could use aws-vault exec $AWS_PROFILE -- terratest. The AWS_DEFAULT_REGION environment variable is required by the tests. Use TT_SKIP_DESTROY=1 to not destroy the infrastructure created during the tests. Use TT_VERBOSE=1 to log all tests as they are run. Use TT_TIMEOUT to set the timeout for the tests, with the value being in the Go format, e.g., 15m. Use TT_TEST_NAME to run a specific test by name.

Terraform Version

Terraform 1.3.0. Pin module version to ~> 2.0.0 . Submit pull-requests to main branch.

Terraform 0.11 and 0.12 are not supported.

Upgrade Notes

1.2.x to 2.x.x

In version 2.x.x, the variables to this module were updated to support the new optional variable functionality introduced in terraform version 1.3.0 and have some breaking changes. The new server_side_encryption variable includes the previous kms_master_key_id and bucket_key_enabled variables as object attributes. The new logging variable includes the bucket and prefix object attributes. This update fixes the multi-step apply introduced by version 1.2.x of this module that was required in order to support AWS provider 4.9. With internal use of objects and optional variables a multi-step apply is no longer needed. To reduce required upgrade modifications, previous use of blank strings for null values is still supported.

1.1.x to 1.2.x

In version 1.2.x, the resources internal to this module were refactored to support the AWS provider with versions >= 4.9, < 5.0. You'll need to import existing resources during the upgrade process. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/version-4-upgrade#s3-bucket-refactor for more information.

License

This project constitutes a work of the United States Government and is not subject to domestic copyright protection under 17 USC § 105. However, because the project utilizes code licensed from contributors and other third parties, it therefore is licensed under the MIT License. See LICENSE file for more information.

Requirements

Name	Version
terraform	>= 1.3.0
aws	>= 4.9, < 5.0

Providers

Name	Version
aws	>= 4.9, < 5.0

Modules

No modules.

Resources

Name	Type
aws_s3_bucket.main	resource
aws_s3_bucket_accelerate_configuration.main	resource
aws_s3_bucket_acl.main	resource
aws_s3_bucket_lifecycle_configuration.main	resource
aws_s3_bucket_logging.main	resource
aws_s3_bucket_notification.main	resource
aws_s3_bucket_ownership_controls.main	resource
aws_s3_bucket_policy.main	resource
aws_s3_bucket_public_access_block.main	resource
aws_s3_bucket_server_side_encryption_configuration.main	resource
aws_s3_bucket_versioning.main	resource
aws_caller_identity.current	data source
aws_canonical_user_id.current	data source
aws_iam_policy_document.policy	data source
aws_partition.current	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
grants	List of ACL policy grants.	list(object({ id = optional(string, "") permissions = list(string) type = string uri = optional(string, "") }))	[]	no
lifecycle_rules	A list of lifecycle rules.	list(object({ id = optional(string) enabled = optional(bool, true) prefix = optional(string) tags = optional(map(string)) transitions = list(object({ date = optional(string) days = optional(number) storage_class = string })) }))	[]	no
logging	The bucket is the bucket that will receive the log objects. The prefix is the key prefix to use when logging, and defaults to "s3/[NAME]/" when not specified.	object({ bucket = string prefix = optional(string, "") })	null	no
name	The name of the AWS S3 bucket.	string	n/a	yes
notifications	List of notifications to configure.	list(object({ id = string queue_arn = string events = list(string) filter_prefix = optional(string) filter_suffix = optional(string) }))	[]	no
object_ownership	The object ownership setting. One of the following values: "BucketOwnerEnforced", "BucketOwnerPreferred", or "ObjectWriter".	string	"ObjectWriter"	no
require_acl_bucket_owner_full_control	Require the object ACL be set to "bucket-owner-full-control" on all PutObject API requests.	bool	false	no
require_tls	Require all API requests to use TLS connections.	bool	false	no
server_side_encryption	The kms_master_key_id is the default KMS used for server-side encryption. If bucket_key_enabled is true, then the bucket is configured to use Amazon S3 Bucket Keys.	object({ bucket_key_enabled = optional(bool, false) kms_master_key_id = string })	null	no
tags	Tags applied to the AWS S3 bucket.	map(string)	{}	no
transfer_acceleration_enabled	If true, then AWS S3 Transfer Acceleration is enabled for the bucket.	bool	false	no
versioning_enabled	Enable versioning. Once you version-enable a bucket, it can never return to an unversioned state. You can, however, suspend versioning on that bucket.	bool	true	no

Outputs

Name	Description
arn	The Amazon Resource Name (ARN) of the AWS S3 Bucket.
bucket_regional_domain_name	The regional domain name of the AWS S3 Bucket.
endpoint_transfer_acceleration	If AWS S3 Transfer Acceleration is enabled, then the endpoint to use over IPv4.
endpoint_transfer_acceleration_dual_stack	If AWS S3 Transfer Acceleration is enabled, then the dual-stack endpoint to use over IPv4 or IPv6.
id	The ID of the AWS S3 Bucket.
region	The AWS region this bucket resides in.