terraform destroy

What Is terraform destroy?

terraform destroy removes all infrastructure resources managed by your Terraform configuration. It is the opposite of terraform apply.

terraform destroy

Terraform reads your configuration and state file, calculates a destroy plan (everything that exists gets removed), shows you the plan, and waits for approval before deleting anything.

Warning: terraform destroy is permanent. Deleted cloud resources cannot be recovered unless you have backups (e.g., RDS snapshots, EBS snapshots). Always review the destroy plan carefully.

The Destroy Plan

Before destroying anything, Terraform shows you exactly what will be deleted:

Notice the reverse dependency order: Terraform destroys in the reverse of the creation order. The EC2 instance is destroyed before the security group, which is destroyed before the subnet, which is destroyed before the VPC. This prevents dependency errors (e.g., you cannot delete a VPC that still has running instances).

When to Use terraform destroy

terraform destroy is most commonly used for ephemeral environments, dev environments, feature branch previews, CI/CD testing environments, and tutorial cleanup.

Partial Destroy with -target

To destroy a single resource (or module) without touching the rest:

# Destroy a single resource
terraform destroy -target=aws_instance.web

# Destroy an entire module
terraform destroy -target=module.database

Terraform will show a destroy plan for only the targeted resource:

Caution: -target can leave your state inconsistent. If other resources depended on the destroyed resource, they still exist in state but their dependency is gone. Always run a full plan after a targeted destroy to check for consistency.

Auto-Approve in CI/CD

Like apply, you can skip the confirmation with -auto-approve:

terraform destroy -auto-approve

This is commonly used in CI/CD pipelines to automatically tear down ephemeral environments:

# GitLab CI, destroy on branch delete
teardown:
  stage: destroy
  script:
    - terraform init -input=false
    - terraform destroy -input=false -auto-approve
  when: manual

Preview the Destroy Plan Without Destroying

To see the destroy plan without any risk, use terraform plan -destroy:

terraform plan -destroy

This is functionally equivalent to terraform destroy without the actual deletion, great for reviewing what would be destroyed before committing.

The destroy Lifecycle Hook

If you want certain resources to be retained even when the configuration is removed, use the prevent_destroy lifecycle argument:

resource "aws_s3_bucket" "critical_data" {
  bucket = "my-production-data"

  lifecycle {
    prevent_destroy = true
  }
}

If you try to destroy this resource (or remove it from your config), Terraform will error:

Use prevent_destroy for critical resources like production databases, S3 buckets with important data, or any resource where accidental deletion would be catastrophic.

terraform fmt, Format Your Code

While you have your terminal open, terraform fmt is a command you will use constantly:

terraform fmt

It automatically formats all .tf files in the current directory to match the Terraform style guide, consistent indentation, aligned = signs, and proper spacing.

# Format and show which files were changed
terraform fmt -diff

# Format all files recursively (including modules)
terraform fmt -recursive

# Check formatting without making changes (useful in CI)
terraform fmt -check

Example, before formatting:

resource "aws_instance" "web" {
ami = "ami-0c55b159cbfafe1f0"
instance_type = "t3.micro"
  tags = {
    Name = "web-server"
  }
}

After terraform fmt:

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"
  tags = {
    Name = "web-server"
  }
}

Pro tip: Add terraform fmt -check to your CI pipeline. If anyone submits unformatted code, the pipeline fails, this enforces consistent style across the team without manual code review comments.

terraform validate, Validate Your Configuration

terraform validate checks your configuration for syntax errors and internal consistency:

terraform validate

Successful output:

Error example:

validate catches:

• Syntax errors (missing braces, typos)
• References to undeclared variables or resources
• Invalid attribute names for a resource type
• Type mismatches (e.g., passing a string where a number is expected)

What validate does NOT check:

• Whether the cloud credentials are valid
• Whether the AMI ID exists in your region
• Whether the VPC ID actually exists
• Anything that requires calling cloud APIs

# Typical workflow before pushing code:
terraform fmt -recursive
terraform validate
terraform plan

Knowledge Check

<MCQExercise exercise={{ id: 'tf-destroy-q1', title: 'Question 1: Destroy Order', description: 'You have a VPC, a subnet inside the VPC, and an EC2 instance inside the subnet. When you run terraform destroy, in what order does Terraform destroy these resources?', options: [ { id: 'a', text: 'VPC → Subnet → EC2 instance (creation order)' }, { id: 'b', text: 'EC2 instance → Subnet → VPC (reverse creation order)' }, { id: 'c', text: 'Alphabetical order: EC2 instance, Subnet, VPC' }, { id: 'd', text: 'All three simultaneously in parallel' }, ], correctId: 'b', explanation: 'Terraform destroys resources in reverse dependency order. The EC2 instance depends on the subnet, which depends on the VPC. So the correct destroy order is EC2 → Subnet → VPC. If Terraform tried to delete the VPC first while the EC2 instance and subnet still existed, the cloud API would return an error (you cannot delete a VPC with active resources).', wrongExplanations: { a: 'Creation order would cause dependency errors. Terraform uses reverse order to avoid these.', c: 'Terraform uses dependency order, not alphabetical.', d: 'Parallel destruction is only done for resources with no dependencies between them. These resources have a dependency chain.', }, }} />

<MCQExercise exercise={{ id: 'tf-destroy-q2', title: 'Question 2: prevent_destroy', description: 'A developer accidentally removes the aws_rds_cluster.production resource block from the Terraform config. What happens when they run terraform apply?', options: [ { id: 'a', text: 'Nothing, Terraform ignores resources that are removed from config' }, { id: 'b', text: 'Terraform shows a plan to delete the RDS cluster and asks for confirmation' }, { id: 'c', text: 'Terraform errors because the config is incomplete' }, { id: 'd', text: 'Terraform moves the RDS cluster to an orphaned state but keeps it running' }, ], correctId: 'b', explanation: 'When a resource is removed from the Terraform configuration, Terraform plans to destroy it (since it is no longer declared). This is why the prevent_destroy lifecycle hook is so valuable for critical resources, it prevents accidental deletion by causing an error when Terraform tries to destroy the resource. Without prevent_destroy, removing the resource block from your config and running apply would delete your production database.', wrongExplanations: { a: 'Terraform does not ignore resources that disappear from config. It plans to destroy them.', c: 'Terraform does not error for removed resources. It treats removal as an intent to destroy.', d: 'There is no "orphaned" state concept in Terraform. Resources are either managed (in state) or not.', }, }} />

<MCQExercise exercise={{ id: 'tf-destroy-q3', title: 'Question 3: terraform fmt', description: 'Your CI/CD pipeline includes terraform fmt -check. A developer submits a merge request with an unformatted .tf file. What happens?', options: [ { id: 'a', text: 'The pipeline auto-formats the file and commits the changes' }, { id: 'b', text: 'The pipeline fails, blocking the merge request until the developer fixes formatting' }, { id: 'c', text: 'The pipeline warns but continues, formatting is optional' }, { id: 'd', text: 'The pipeline skips the formatting check for merge requests' }, ], correctId: 'b', explanation: 'terraform fmt -check exits with a non-zero exit code if any files need formatting (without making changes). In CI/CD, a non-zero exit code fails the pipeline step. This blocks the merge request, enforcing that all committed code must be properly formatted. The developer needs to run terraform fmt locally and push the fixed files.', wrongExplanations: { a: 'The -check flag only checks, it never modifies files. You need terraform fmt (no flag) to actually format.', c: 'The -check flag causes a non-zero exit code on unformatted files, which fails the CI step. It is not advisory.', d: 'CI pipelines do not automatically skip steps for MRs. The same pipeline runs regardless of trigger type unless explicitly configured.', }, }} />