How to Create an AWS S3 Bucket with Terraform

The basic bucket

resource "aws_s3_bucket" "analytics" {
  bucket = "my-company-analytics"   # globally unique name
}

That's the whole resource. bucket is the (globally unique) name. Run it with:

terraform init
terraform apply -auto-approve

"Unsupported argument" - the v4+ gotcha

Before AWS provider v4 you set versioning, server_side_encryption_configuration, etc. inside the bucket resource. In v4+ those are separate resources, so old-style arguments now error:

Error: Unsupported argument
  on main.tf: an argument named "versioning" is not expected here.

The fix is to break them out:

resource "aws_s3_bucket_versioning" "analytics" {
  bucket = aws_s3_bucket.analytics.id
  versioning_configuration { status = "Enabled" }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "analytics" {
  bucket = aws_s3_bucket.analytics.id
  rule {
    apply_server_side_encryption_by_default { sse_algorithm = "AES256" }
  }
}

(A plain typo - buckkket = "..." - produces the same "Unsupported argument" error; read the line number Terraform prints and fix that argument.)

Lock it down (you almost always want these)

resource "aws_s3_bucket_public_access_block" "analytics" {
  bucket                  = aws_s3_bucket.analytics.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

How to debug a failing apply

• Read the error - Terraform names the argument and the line.
• terraform validate catches syntax/arg errors before you hit AWS.
• terraform plan shows exactly what will be created before apply.

Common aws_s3_bucket errors

• BucketAlreadyExists / BucketAlreadyOwnedByYou - S3 bucket names are globally unique across every AWS account. Pick a name nobody has taken (add a suffix), or use bucket_prefix to let AWS append randomness.
• Unsupported argument - on provider v4+, versioning, server_side_encryption_configuration, acl, and lifecycle rules moved out of aws_s3_bucket into their own resources (aws_s3_bucket_versioning, and so on). Split them out.
• BucketNotEmpty on destroy - Terraform will not delete a bucket with objects in it. Set force_destroy = true if you want terraform destroy to empty it first.
• Invalid name - bucket names must be lowercase, 3-63 characters, DNS-compliant, with no underscores.

Run terraform plan after every change - the AWS provider validates most of these before any API call, so you catch them locally instead of mid-apply.