🌍 Terraform State File Management — Explained by Raees Yaqoob Qazi

 

Raees Qazi | DevOps Engineer | Learner | Mentor | Creator

Hello everyone,
Today I’m going to explain an important Terraform concept — Terraform State File Management — in a simple and practical way.

🧠 What is a Terraform State File?

When we use Terraform to create resources (like an EC2 instance on AWS), Terraform automatically generates a file called terraform.tfstate after applying the configuration.

This state file contains complete information about your infrastructure, such as:

  • The EC2 instance details (like ID and status)
  • IP addresses
  • Resource configurations and dependencies

In short — this file acts as a map of your entire infrastructure, so Terraform knows what already exists when you run future commands like terraform plan or terraform apply.

❓ Why Do We Need Terraform State Management?

You might be wondering — if Terraform already has a state file, why do we need to manage it?

Let me explain with a real-world example 👇

Imagine me (Raees) and my teammate Saad, both working as DevOps engineers on the same project.

  • I create one EC2 instance using Terraform. My local Terraform folder now has a state file showing one instance.
  • Later, Saad also works on the same project and creates two EC2 instances. His local state file now shows two instances.

Now, we have a problem — both of us have different versions of the state file. Terraform will get confused because it doesn’t know the actual state of the infrastructure.

This situation is very common in team environments — and that’s exactly why we need Terraform State Management.

🧩 Solution: Remote Backend and State Locking

To solve this issue, we use remote backends like AWS S3 (to store the state file) and DynamoDB (to handle locking).

Here’s how it works:

  1. We store our terraform.tfstate file in an S3 bucket instead of keeping it locally.
  2. We enable state locking using DynamoDB — so only one engineer can modify the state at a time.

⚙️ Why Not Store the State File in Git?

Good question!
You might think storing it in Git is easier since Git is great for version control.
However, we don’t store state files in Git because they contain sensitive information (like resource IDs, IPs, and secrets).
Putting that in a public or shared Git repo would be a serious security risk.

That’s why S3 + DynamoDB is the best approach — secure, centralized, and efficient.

🔁 How the Process Works

Here’s the workflow:

  1. Create an S3 bucket to store the Terraform state file.
  2. Create a DynamoDB table for state locking.
  3. When I (Raees) start working, Terraform automatically creates a lock ID in DynamoDB.

This lock prevents others (like Saad) from making changes at the same time.

Once I finish and Terraform releases the lock, Saad can then start his changes.

This ensures that only one person edits the state at a time — preventing conflicts and maintaining infrastructure consistency.

🧪 Practical Implementation

Before starting, make sure your AWS CLI is already configured with your credentials (access key, secret key, region, and output format).

Step 1: Create a directory for your project

mkdir remote_infra
cd remote_infra

Step 2: Create the terraform.tf file

vim terraform.tf

Add the following content:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "6.15.0"
    }
  }
}

Then exit and save (:wq).
Initialize Terraform:

terraform init

Step 3: Create the provider file

vim providers.tf
provider "aws" {
  region = "ca-central-1"
}

Step 4: Create resources for S3 and DynamoDB

vim resources.tf
resource "aws_s3_bucket" "my_s3_bucket" {
  bucket = "terrastate-demo-state-bucket"
}
resource "aws_dynamodb_table" "my_dynamodb_table" {
  name         = "terrastate-demo-state-table"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"  attribute {
    name = "LockID"
    type = "S"
  }
}

Apply the configuration:

terraform plan
terraform apply

Now both your S3 bucket and DynamoDB table are created.

Step 5: Configure Remote Backend

cd ..
mkdir remote_demo
cd remote_demo
vim terraform.tf

Add this content:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "6.15.0"
    }
  }
  backend "s3" {
    bucket         = "terrastate-demo-state-bucket"
    key            = "terraform.tfstate"
    region         = "ca-central-1"
    dynamodb_table = "terrastate-demo-state-table"
  }
}

Initialize Terraform again:

terraform init

You’ll notice that no local state file is created now — because it’s stored in S3.

Step 6: Create an EC2 Instance

vim main.tf
provider "aws" {
  region = "ca-central-1"
}
resource "aws_instance" "my_ec2_instance" {
  ami           = "ami-xxxxxxx"
  instance_type = "t2.micro"  tags = {
    Name = "terraweek-instance"
  }
}

Then run:

terraform plan
terraform apply

Terraform will create your EC2 instance — and your state file will be securely saved and locked in the S3 bucket.

If someone else tries to make changes during this time, the lock ID in DynamoDB will prevent it until your operation is complete.

Step 7: View the Remote State File

If you ever need to check the state, simply run:

terraform state pull

This command pulls the state file from S3 for inspection.

✅ Conclusion

With S3 + DynamoDB, we can:

  • Manage Terraform state files securely
  • Avoid conflicts between multiple DevOps engineers
  • Maintain full visibility and consistency of our infrastructure

That’s how Terraform State Management works in real-world projects.

I hope this explanation helped you understand the concept clearly.
If you found it useful, please share it with others who are learning Terraform!

🌐 Online References

Comments

Post a Comment