S3 backend configuration in Terraform - Commands & Configuration

Introduction

When you use Terraform to manage infrastructure, you need a place to save the current state of your resources. The S3 backend lets you store this state file safely in an Amazon S3 bucket, so multiple people or systems can work together without conflicts.

When you want to share Terraform state files between team members safely.

When you want to keep your Terraform state file backed up and durable.

When you want to enable locking of the state file to prevent simultaneous changes.

When you manage infrastructure across multiple environments and want centralized state storage.

When you want to use Terraform Cloud features but prefer to keep state in your AWS account.

Config File - main.tf

main.tf

terraform {
  backend "s3" {
    bucket = "example-terraform-state"
    key    = "envs/prod/terraform.tfstate"
    region = "us-east-1"
    encrypt = true
  }
}

provider "aws" {
  region = "us-east-1"
}

This configuration tells Terraform to use an S3 bucket named example-terraform-state to store the state file.

The key defines the path inside the bucket where the state file is saved.

The region specifies the AWS region of the bucket.

The encrypt option ensures the state file is stored encrypted.

The AWS provider block sets the region for AWS resources.

Commands

This command initializes Terraform and configures the S3 backend to store the state file remotely.

Terminal

terraform init

Expected Output

Initializing the backend...



Successfully configured the backend "s3"!



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see

any changes that are required for your infrastructure. All Terraform commands

should now work.



If you ever set or change modules or backend configuration, rerun this command

to reinitialize your working directory. If you forget, other commands will

detect it and remind you to do so if necessary.

This command shows what Terraform will do based on the current configuration and state stored in the S3 backend.

Terminal

terraform plan

Expected Output

Refreshing Terraform state in-memory prior to plan...



No changes. Infrastructure is up-to-date.



This means that Terraform did not detect any differences between your

configuration and real physical resources that exist. As a result, no

actions need to be performed.

Key Concept

If you remember nothing else from this pattern, remember: storing Terraform state in an S3 bucket allows safe sharing and locking of infrastructure state across teams.

Common Mistakes

Not running 'terraform init' after adding the S3 backend configuration.

Terraform will not configure the backend and will continue using the local state file, causing confusion and possible conflicts.

Always run 'terraform init' after changing backend settings to initialize the remote state storage.

Using a bucket name that does not exist or is in a different AWS region without proper configuration.

Terraform will fail to connect to the S3 backend and cannot store or retrieve the state file.

Create the S3 bucket in the specified region before using it, and ensure the region in the backend matches the bucket's region.

Not setting 'encrypt = true' in the backend configuration.

The state file will be stored unencrypted, risking exposure of sensitive information.

Always enable encryption by setting 'encrypt = true' to protect your state file.

Summary

Configure the S3 backend in Terraform to store the state file remotely and securely.

Run 'terraform init' to initialize the backend and prepare Terraform to use the S3 bucket.

Use 'terraform plan' to verify that Terraform can read the state from the S3 backend and show planned changes.