Terraform Taint vs. Replace: Why Replace is the Better Option for Your Infrastructure

Rhegisan Jebas
3 min readApr 13




When working with Terraform, you may find that resources are modified outside of Terraform’s control. This can cause issues with Terraform’s state management, making it difficult to know what resources are under Terraform’s control and what changes have been made. To address this issue, terraform provides two commands: terraform taint and terraform replace.


The terraform taint command marks a resource as “tainted”, which means that terraform will destroy and recreate the resource the next time it runs. This allows you to bring the resource back under Terraform’s management, even though it has been manually modified.

For example, if you manually modify an EC2 instance outside of Terraform, you can use terraform taint to mark the instance as tainted and terraform will recreate it the next time you run terraform apply.

Here’s an example of how to use terraform taint:

$ terraform taint aws_instance.web_server
Resource instance aws_instance.web_server has been marked as tainted.

In this example, terraform taint aws_instance.web_server marks the aws_instance resource named web_server as tainted.

However, it’s worth noting that taint is considered a deprecated command in Terraform, and it’s not recommended for use in new code.


The terraform replace command is similar to taint, but it provides more fine-grained control over how resources are replaced. Specifically, replace allows you to replace a resource with a new resource of a different type or with a different set of attributes.

For example, if you need to change an EC2 instance from a t2.micro to a t2.small instance type, you can use terraform replace to create a new instance of the desired type, and then destroy the old instance.

Here’s an example of how to use terraform replace:

$ terraform replace aws_instance.web_server
aws_instance.new_web_server: Creating...
ami: "ami-0c55b159cbfafe1f0"
instance_type: "t2.small"
subnet_id: "subnet-0123456789abcdef0"
vpc_security_group_ids.#: "1"
vpc_security_group_ids.0: "sg-0123456789abcdef0"
aws_instance.web_server: Destroying... [id=i-0123456789abcdef0]
aws_instance.web_server: Destruction complete after 1m5s
aws_instance.new_web_server: Creation complete after 1m10s

Apply complete! Resources: 1 added, 1 destroyed.

In this example, terraform replace aws_instance.web_server creates a new aws_instance resource with the desired attributes, and destroys the old aws_instance resource.


While terraform taint and terraform replace are similar commands, they work in slightly different ways.

The main difference between taint and replace is how they handle resource modifications. Taint simply marks a resource as tainted, and Terraform destroys and recreates it the next time it runs. This can be useful for bringing a resource back under Terraform’s management, but it doesn’t provide any control over how the resource is recreated.

Replace, on the other hand, creates a new resource with the desired attributes, and then destroys the old resource. This provides more control over how resources are replaced, and can be especially useful when you need to change a resource’s type or attributes.

Additionally, because replace creates a new resource instead of simply marking the old one as tainted, it’s safer and less prone to unintended consequences. By creating a new resource and destroying the old one, you can ensure that your changes are safe and predictable.


While both terraform taint and terraform replace are useful tools for managing resources that have been modified outside of Terraform’s control, terraform replace is generally considered to be a better option because it provides more control and is safer to use.

It’s also worth noting that taint is considered a deprecated command in Terraform, and it’s not recommended for use in new code. Instead, you should use replace or other techniques, such as using an external data source or importing an existing resource, to bring modified resources back under Terraform’s control.

Thanks for reading! I hope you found it helpful and informative.

If you have any questions or comments, please don’t hesitate to leave them in the comments section below. I’ll do my best to respond to each one.

If you’d like to stay up to date on terraform related content, be sure to follow me on Medium and LinkedIn. I’d love to connect with you and hear your thoughts.



Rhegisan Jebas

Passionate DevOps engineer sharing insights on building high-quality software through automation, containerization, and continuous delivery.