Terraform Taint

Terraform Taint [Replace Resource]

Terraform taint help us in several scenarios when we have problem with our resources in the Terraform state. However, on Terraform v0.15.2, the taint command was deprecated, but we have a new argument that does the same functionality, and we will learn both; if you are using the older version, you can still use the terraform taint.

What is terraform taint? 

The terraform taint command tells Terraform that a specific object has been damaged or degraded. Terraform symbolizes this by flagging the resource as “tainted” in the Terraform state. Also, Terraform will suggest replacing it in the following plan we make.

When use the Terraform Taint?

A resource may become damaged or degraded in some circumstances, and the Terraform cannot automatically notice it. For instance, if some application is running inside a virtual machine crashes, but the virtual machine itself is still running, Terraform will generally have no way to catch and react to the issue because Terraform only directly controls the resource as a whole.

Terraform Taint Example

Let’s see one example of how to use Terraform Taint.

How to run terraform taint: Usage

terraform taint [argument] <address>

The address argument is the address of the resource from the Terraform state to set as tainted. 

How do I find the resource address?

We can perform the command below to list all resources in the terraform state.

terraform state list

You will see the output like this one:

(Add more example)

So, when you identify the address from the resource that you are looking for, you need to run:

terraform taint aws_instance.webserver[0]

After, run:

terraform plan

And finally:

terraform apply

So, the resource we set the flag as “taint” will be destroyed and re-created in the apply phase.

Replace and Keep the old Resource

One approach that saved me a lot of time was when I needed to replace one resource, but I didn’t want to lose it. So, you may think, why would we like to do it? Imagine if you have some issue with one EC2 instance, and you need to keep that instance running until you have time to troubleshoot what is going wrong with it by checking the logs later. 

How do we tell Terraform to replace it but keep the old one?

We can remove it from the terraform state. So, it means that the Terraform will “forget” that this instance exists. So, the next time we execute the planning phase, it will create a new one and not mark that instance to be destroyed because the terraform doesn’t manage that specific instance anymore. 

So if we run:

terraform state rm aws_instance.webserver[0]

We will replace it with a new instance but keep the old one. There is no rule for that; it’s up to you or your scenario. It’s just a little trick that saves us sometimes.

Terraform Taint Alternative

Terraform Force Replacement

We saw in the beginning that Terraform deprecated the terraform taint. However, we still have a command that supports that goal for us.

Using the -replace argument with terraform apply or terraform plan, to force Terraform to replace a resource even though there are no modifications that would require it.

Terraform Apply Replace Example

So, to use terraform apply:

terraform apply -replace="aws_instance.webserver[0]"

or can we use the terraform plan:

terraform plan -replace="aws_instance.webserver[0]"

Terraform Taint or Terraform Apply?

Terraform recommends using the apply command. Let’s see why.

When we use -replace argument with terraform apply, the modification will be mirrored in the terraform plan, allowing us to understand how it will impact our infrastructure before performing any external-visible step. On the other hand, when we utilize terraform taint, other users could produce a new plan against our tainted resource before we can review the results.

Terraform Untaint

Suppose Terraform has set a resource as tainted, but you feel it is working perfectly and does not desire to replace it. We can override Terraform’s decision utilizing the terraform untaint command in that scenario.


terraform untaint <address>

So, we can run:

terraform untaint aws_instance.webserver[0]


So, we learned that the terraform taint command is used for replacing a resource, whatever the reason. Also, we have alternatives where we can use the “terraform apply” or “terraform plan” command with a “replace” argument.

Also, we can undo the “terraform taint” or “replace” by executing the terraform untaint.

Boost your Terraform skills:

How to use Terraform Modules

How to create complex expressions using Terraform Template.

What is the difference between Locals and Terraform Variables?

How to use the Terraform Data on your modules.

What are the advantages of Terraform Output?

How to use the Terraform Workspace

Learn how to create multiple copies from the same resource on Terraform.

How to create a Pipeline on Gitlab to execute a Terraform code?

Leave a Comment

Your email address will not be published. Required fields are marked *

Free PDF with a useful Mind Map that illustrates everything you should know about AWS VPC in a single view.