Site icon JD Bots

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

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:

main.tf

resource "terraform_data" "shop_sign" {
  input            = "Open"
  triggers_replace = "v1"
}

Run tofu init, then tofu apply and type yes:

Terminal

tofu init
tofu apply

Output (the lines that matter)

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:

Terminal

tofu apply

Output (the lines that matter)

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.
Changing input updates the resource in place.

Type yes to apply it.

Step 3: Make a Change That Replaces It

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

Terminal

tofu apply

Output (the lines that matter)

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.
Changing triggers_replace replaces the resource.

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

Output (the lines that matter)

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:

Output (the lines that matter)

      ~ 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.

Terminal

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.

Related

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.

Exit mobile version