Terraform Remote Backend with S3 and DynamoDB

Q: How do I migrate an existing local state file?

Run: ``bash terraform init `` Terraform will prompt you to migrate the existing state file to the configured backend.

Remote Backends with AWS S3 in Terraform allow teams to store Terraform state in a centralized location instead of keeping it on individual machines.

This becomes important as soon as multiple engineers start managing the same infrastructure. A remote backend improves collaboration, reduces the risk of state corruption, and makes Terraform workflows more reliable.

In this guide, you'll learn how to configure Remote Backends with AWS S3 in Terraform, enable state locking with DynamoDB, migrate existing state files, and follow production-ready best practices.

Why Remote Backends Matter in Terraform

Terraform uses a state file to track infrastructure resources. If you're unfamiliar with how state works, start by understanding the Terraform state file.

By default, Terraform stores state locally in a file named terraform.tfstate.

Local state works for learning and small personal projects, but it quickly becomes a problem when multiple people manage the same infrastructure.

Challenges with Local State

No centralized source of truth
Difficult team collaboration
Increased risk of accidental state deletion
No protection against concurrent Terraform operations
Sensitive information may be stored in the state file

Imagine two engineers running terraform apply at the same time. Without state locking, both operations could modify the same state file and create inconsistencies.

This is where remote backends become essential.

What Is a Remote Backend in Terraform?

A remote backend is a shared location where Terraform stores its state file.

Instead of storing state on a laptop or local server, Terraform reads and writes state from a centralized backend.

Terraform supports multiple backend types through the official Terraform Backend Documentation.

AWS S3 is one of the most commonly used backend options because it is durable, highly available, and integrates well with AWS security controls.

For production environments, S3 is typically combined with DynamoDB for state locking. You can learn more about the overall workflow in our guide on remote state and state locking in Terraform.

Benefits of Using AWS S3 as a Backend

Centralized state storage
Secure access through IAM policies
State file versioning
Server-side encryption
Team collaboration support
State locking with DynamoDB
Protection against accidental state overwrites

Prerequisites for Setting Up Remote Backends with AWS S3 in Terraform

Before configuring the backend, make sure the following resources already exist.

Create an S3 Bucket

The S3 bucket will store your Terraform state file.

If you need help creating one, follow our guide on how to create an S3 bucket using Terraform.

Create a DynamoDB Table

The DynamoDB table is used for state locking.

You can also learn how to create a DynamoDB table with Terraform.

The table should include:

Partition key: LockID
Type: String

Gather Required Information

Make note of:

S3 bucket name
AWS region
State file path
DynamoDB table name

How to Configure Remote Backends with AWS S3 in Terraform

Terraform backend settings are configured inside the terraform block.

A typical configuration looks like this:

terraform {
  backend "s3" {
    bucket         = "techalmirah-terraform-state-bucket01"
    key            = "finance/terraform.tfstate"
    region         = "us-west-1"
    dynamodb_table = "state-locking"
  }
}

Understanding the Backend Parameters

bucket

The S3 bucket where Terraform stores the state file.

bucket = "techalmirah-terraform-state-bucket01"

key

The path and filename of the state file.

key = "finance/terraform.tfstate"

region

AWS region where the bucket exists.

region = "us-west-1"

dynamodb_table

The DynamoDB table used for state locking.

dynamodb_table = "state-locking"

Production Example

Many organizations organize Terraform state by environment and application.

terraform {
  backend "s3" {
    bucket         = "company-prod-terraform-state"
    key            = "networking/prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-locks"
  }
}

This structure helps keep environments separated and easier to manage.

Recommended Terraform Project Structure

Keeping backend configuration separate from resource definitions improves maintainability.

A common structure looks like this:

project/
├── terraform.tf
├── main.tf
├── variables.tf
├── outputs.tf
└── providers.tf

File Responsibilities

terraform.tf stores backend configuration
main.tf contains infrastructure resources
variables.tf defines input variables
outputs.tf defines outputs
providers.tf configures providers

You can learn more about project organization in our guide on Terraform configuration directory structure.

Initializing the Remote Backend

After adding the backend configuration, initialize Terraform.

Step 1: Run Terraform Init

terraform init

Terraform will initialize the backend and validate the configuration.

Step 2: Migrate Existing State

If a local state file exists, Terraform will ask whether you want to migrate it.

Respond:

yes

Terraform then uploads the existing state file to S3.

Step 3: Verify Migration

Confirm that:

State file exists in S3
DynamoDB lock table is accessible
Terraform operations complete successfully

How Terraform Uses the Remote Backend

Once initialization is complete, Terraform follows a predictable workflow.

Reads the state from S3.
Acquires a lock in DynamoDB.
Executes the operation.
Updates the state file.
Releases the lock.

This prevents multiple users from modifying infrastructure simultaneously.

Pro Tip: Enable S3 Versioning

Enable bucket versioning before storing Terraform state.

If a state file becomes corrupted or someone accidentally modifies it, S3 versioning allows you to recover a previous version quickly.

According to the official AWS documentation, versioning helps preserve, retrieve, and restore every version of an object stored in an S3 bucket.

Reference: AWS S3 Versioning Documentation

Benefits of Using AWS S3 Remote Backends

Secure State Management

S3 supports:

Server-side encryption
IAM-based access control
Audit logging through AWS CloudTrail

This helps protect sensitive information stored in Terraform state.

Safe Team Collaboration

Remote state and locking make collaboration much safer.

Only one Terraform operation can hold the lock at a time, reducing the risk of conflicting changes.

Scalability

AWS S3 is designed for durability and scalability.

As infrastructure grows, the backend continues to support larger teams and more complex environments without requiring architectural changes.

Common Mistakes to Avoid

Forgetting S3 Versioning

Without versioning, recovering from accidental state changes becomes much harder.

Not Enabling State Locking

Using S3 without DynamoDB locking leaves the state vulnerable to concurrent modifications.

Avoid storing development, staging, and production resources in the same state file.

Use separate state files for each environment.

Committing State Files to Git

Terraform state files often contain sensitive information.

Never commit state files to source control repositories.

Using Excessive Permissions

Grant only the permissions required for Terraform to access the backend resources.

Follow the principle of least privilege when creating IAM policies.

As you continue learning Terraform, these guides will help you build a stronger foundation:

Frequently Asked Questions (FAQs)

Why use a remote backend in Terraform?

Remote backends provide centralized state management, improve collaboration, enhance security, and support state locking.

Can I use S3 without DynamoDB?

Yes.

Terraform can store state in S3 without DynamoDB, but you lose state locking capabilities. This increases the risk of concurrent operations modifying the state simultaneously.

What is the role of DynamoDB in a remote backend?

DynamoDB provides a locking mechanism that prevents multiple Terraform operations from updating the same state file at the same time.

How do I migrate an existing local state file?

Run:

terraform init

Terraform will prompt you to migrate the existing state file to the configured backend.

Is storing Terraform state in S3 secure?

Yes, when implemented correctly.

Use:

S3 versioning
Encryption
IAM policies
Block public access settings
CloudTrail auditing

Should Terraform state files be committed to Git?

No.

State files can contain infrastructure metadata and sensitive information. They should be stored in a secure remote backend instead of source control.

Final Thoughts

Moving from local state storage to Remote Backends with AWS S3 in Terraform is one of the first steps toward a production-ready Infrastructure as Code workflow.

With S3 handling state storage and DynamoDB providing locking, teams gain a secure and reliable way to collaborate on infrastructure changes.

A properly configured backend reduces operational risk, protects critical infrastructure data, and makes Terraform easier to use as your environment grows.