Elevating IaC Workflows with Spacelift Stacks and Dependencies 🛠️

Register for the July 23 demo →


How to Rename an AWS S3 Bucket in Terraform – Step by Step

How to rename aws s3 bucket

Occasionally you might want to rename an AWS S3 bucket you are managing with Terraform. However, names of S3 buckets are immutable, which means you can’t change them directly. If you tried, Terraform would destroy the old one and then create a new one, resulting in data loss.

To avoid this, you need to create a new bucket with the desired name, move the data over to it, make the relevant Terraform state replacements, and finally delete the old bucket.

In this post you will learn how to rename an AWS S3 bucket in Terraform. First things first – let’s say you have a bucket definition in your Terraform code:

resource “aws_s3_bucket” “my_bucket” {
    bucket = “old-name”

and you want to change the name of the bucket to new-name.

Step 1 - Create the new bucket

Firstly, we’ll need to create a new bucket. You can do this using the AWS CLI or the AWS console. Just make sure to properly replicate the old settings, especially the ACL (so that your data doesn’t accidentally become public).

Now, we can copy all the files from the old to the new bucket:

aws s3 sync s3://old-name s3://new-name

Step 2 - Modify the State

Now that we have our new bucket, we need to remove the old one from our Terraform state and import the new one in its place:

terraform state rm aws_s3_bucket.my_bucket
terraform import aws_s3_bucket.my_bucket new-name

If you tried to run Terraform now, it would show you that there’s drift—and yes, there would be! We’ve just imported a bucket into a resource which still has old-name in the config.

Step 3 - Change the Code

That’s why we now have to finally change the name of the bucket in our Terraform config:

resource “aws_s3_bucket” “my_bucket” {
    bucket = “new-name”

If you run Terraform now, you’ll see that there are no changes to be made.

Step 4 - Do a Cleanup

If you want to, you can now delete your old bucket using:

aws s3 rm s3://old-name --recursive
aws s3 rb s3://old-name

Make sure all the data has successfully been copied over to the new bucket.

Step 5 - Run the Above Arbitrary AWS CLI Commands if You’re Using Spacelift

If you’re using Spacelift then you can use tasks to run the above arbitrary AWS CLI commands. The default runner image already contains the AWS CLI, so no changes are necessary there.

One additional thing you can do is lock the Stack while you’re running the migration, this way nobody will accidentally run Terraform or make any other changes while you’re moving the data.

And that’s it! If you have any questions about how to rename an AWS S3 bucket, drop me a line in the comments and I’ll get back to you straight away.

Note: New versions of Terraform will be placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that will expand on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6. OpenTofu retained all the features and functionalities that had made Terraform popular among developers while also introducing improvements and enhancements. OpenTofu is the future of the Terraform ecosystem, and having a truly open-source project to support all your IaC needs is the main priority.

Manage Terraform Better and Faster

If you are struggling with Terraform automation and management, check out Spacelift. It helps you manage Terraform state, build more complex workflows, and adds several must-have capabilities for end-to-end infrastructure management.

Start free trial

How can Spacelift stacks & dependencies elevate your IaC workflows?

Don’t miss our July 23 webinar.

Register for the webinar