Skip to main content
0 reactions

OpenTofu Update in Place vs Replace: How to Tell from the Plan

A Terminal window with an OpenTofu plan: terraform_data.shop_sign must be replaced, marked -/+, triggers_replace changes from v1 to v2, the id becomes known after apply, and the summary says 1 to add, 0 to change, 1 to destroy.
Changing triggers_replace replaces the resource.

When you change a resource in OpenTofu®, the plan does one of two things to it. It either updates it in place, changing the existing object, or replaces it, destroying it and creating a new one. The difference matters: a replaced database or server starts from scratch.

This guide shows both on one small resource, so you can spot them in any plan.

Prerequisites

Step 1: Create a Resource

The example uses terraform_data, a resource built into OpenTofu that only stores values, so it needs no provider and creates nothing outside OpenTofu. Create main.tf:

Plain text
resource "terraform_data" "shop_sign" {
  input            = "Open"
  triggers_replace = "v1"
}
  • input is a value OpenTofu stores and can change in place.
  • triggers_replace is a value that forces a replacement when it changes.

Run tofu init, then tofu apply and type yes:

Bash
tofu init
tofu apply
Plain text
terraform_data.shop_sign: Creating...
terraform_data.shop_sign: Creation complete after 0s [id=00000000-0000-0000-0000-000000000000]

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

Step 2: Make a Change That Updates in Place

Change input from "Open" to "Closed", then run tofu apply:

Bash
tofu apply
Plain text
OpenTofu used the selected providers to generate the following execution plan. Resource
actions are indicated with the following symbols:
  ~ update in-place (current -> planned)

OpenTofu will perform the following actions:

  # terraform_data.shop_sign will be updated in-place
  ~ resource "terraform_data" "shop_sign" {
        id               = "00000000-0000-0000-0000-000000000000"
      ~ input            = "Open" -> "Closed"
      ~ output           = "Open" -> (known after apply)
        # (1 unchanged attribute hidden)
    }

Plan: 0 to add, 1 to change, 0 to destroy.
A Terminal window with an OpenTofu plan: terraform_data.shop_sign will be updated in-place, input changes from Open to Closed, the id stays the same, and the summary says 0 to add, 1 to change, 0 to destroy.
Changing input updates the resource in place.
  • The symbol is ~ and the line says will be updated in-place.
  • The id stays the same: it’s still the same object.
  • The summary counts it under change: 1 to change.

Type yes to apply it.

Step 3: Make a Change That Replaces It

Change triggers_replace from "v1" to "v2", then run tofu apply:

Bash
tofu apply
Plain text
OpenTofu used the selected providers to generate the following execution plan. Resource
actions are indicated with the following symbols:
-/+ destroy and then create replacement

OpenTofu will perform the following actions:

  # terraform_data.shop_sign must be replaced
-/+ resource "terraform_data" "shop_sign" {
      ~ id               = "00000000-0000-0000-0000-000000000000" -> (known after apply)
      ~ output           = "Closed" -> (known after apply)
      ~ triggers_replace = "v1" -> "v2"
        # (1 unchanged attribute hidden)
    }

Plan: 1 to add, 0 to change, 1 to destroy.
A Terminal window with an OpenTofu plan: terraform_data.shop_sign must be replaced, marked -/+, triggers_replace changes from v1 to v2, the id becomes known after apply, and the summary says 1 to add, 0 to change, 1 to destroy.
Changing triggers_replace replaces the resource.
  • The symbol is -/+ and the line says must be replaced.
  • The id becomes (known after apply): the new object gets a new one.
  • The summary counts it twice: 1 to add and 1 to destroy.

Type yes. OpenTofu destroys the old object, then creates the new one:

Plain text
terraform_data.shop_sign: Destroying... [id=00000000-0000-0000-0000-000000000000]
terraform_data.shop_sign: Destruction complete after 0s
terraform_data.shop_sign: Creating...
terraform_data.shop_sign: Creation complete after 0s [id=11111111-1111-1111-1111-111111111111]

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

Which Change Forces a Replacement?

Each resource type decides which of its arguments can change in place. For resources from a provider, the plan marks the argument that forces the replacement. In this example from the local_file resource, changing content replaces the file:

Plain text
      ~ content              = "Open every day" -> "Open every day, 9 to 5" # forces replacement

Each resource’s page on the OpenTofu Registry lists its arguments: see how to find provider docs on the OpenTofu Registry.

Warning: Read every -/+ line before you type yes. Replacing a database or a disk can lose its data, and replacing a server or container takes it offline for a moment.

Clean Up

Run tofu destroy and type yes, then delete the folder.

Bash
tofu destroy

FAQ

Why did the output change too in Step 2?

output is the value terraform_data reports back. It’s computed from input, so it’s (known after apply) until the new value is applied.

Can I make OpenTofu create the new object before destroying the old one?

Yes, with the create_before_destroy lifecycle rule, which a later part of the OpenTofu Tutorial covers.

Conclusion

Two symbols tell you what a change will do: ~ updates the existing object, and -/+ replaces it with a new one. Look for must be replaced and # forces replacement in every plan you apply.

Additional Resources

OpenTofu® is a registered trademark of LF Projects, LLC. Other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by the OpenTofu project.

0 comments