Terraform apply -replace flag - Commands & Configuration

Introduction

Sometimes you want to force Terraform to destroy and recreate a specific resource without changing the rest of your infrastructure. The -replace flag helps you do exactly that during the apply step.

When a resource is stuck in a bad state and you want to recreate it without affecting others.

When you want to update a resource that requires replacement but don't want to change your whole plan.

When debugging infrastructure issues by recreating a single resource.

When a resource's configuration changed outside Terraform and you want to sync by recreating it.

When you want to test changes on a resource by forcing its replacement safely.

Config File - main.tf

main.tf

terraform {
  required_version = ">= 1.5.0"
}

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

resource "aws_s3_bucket" "example_bucket" {
  bucket = "example-terraform-replace-flag"
  acl    = "private"
}

This Terraform configuration creates a simple AWS S3 bucket named "example-terraform-replace-flag" in the us-east-1 region. The terraform block ensures the Terraform version is 1.5.0 or newer, which supports the -replace flag.

The aws_s3_bucket resource defines the bucket with private access.

Commands

Initializes the Terraform working directory, downloads provider plugins, and prepares the environment.

Terminal

terraform init

Expected Output

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.

Applies the Terraform configuration to create the S3 bucket without asking for confirmation.

Terminal

terraform apply -auto-approve

Expected Output

aws_s3_bucket.example_bucket: Creating...

aws_s3_bucket.example_bucket: Creation complete after 3s [id=example-terraform-replace-flag]



Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

→

-auto-approve - Skips interactive approval before applying changes.

Forces Terraform to destroy and recreate the S3 bucket resource while leaving other resources untouched.

Terminal

terraform apply -replace=aws_s3_bucket.example_bucket -auto-approve

Expected Output

aws_s3_bucket.example_bucket: Destroying... [id=example-terraform-replace-flag]

aws_s3_bucket.example_bucket: Destruction complete after 2s

aws_s3_bucket.example_bucket: Creating...

aws_s3_bucket.example_bucket: Creation complete after 3s [id=example-terraform-replace-flag]



Apply complete! Resources: 1 added, 0 changed, 1 destroyed.

→

-replace - Specifies the resource to force replace.

→

-auto-approve - Skips confirmation prompt.

Lists all resources currently tracked in the Terraform state to verify the resource exists after replacement.

Terminal

terraform state list

Expected Output

aws_s3_bucket.example_bucket

Key Concept

If you remember nothing else from this pattern, remember: the -replace flag forces Terraform to destroy and recreate a specific resource during apply without affecting others.

Common Mistakes

Using -replace with an incorrect resource address.

Terraform will error because it cannot find the resource to replace.

Use the exact resource address as shown in terraform state list, including module paths if any.

Forgetting to use -auto-approve and expecting no prompt.

Terraform will pause and wait for manual confirmation, blocking automation.

Add -auto-approve to skip confirmation when running in scripts or automation.

Expecting -replace to update the resource without destroying it.

-replace always destroys and recreates the resource, which may cause downtime or data loss.

Use -replace only when you want a full replacement; otherwise, update configuration normally.

Summary

Initialize Terraform with terraform init to prepare the environment.

Apply the configuration normally with terraform apply to create resources.

Use terraform apply -replace=resource_address to force recreate a specific resource.

Verify the resource state with terraform state list after replacement.