information in 'Removing moved Blocks' seems to be false

[Netkracker]

Terraform Version

terraform v1.9.4
on windows amd_64

(We use TFE so its not my local system and this happens on every tf core version we have in use  1.3.x - 1.5.X)

Affected Pages

https://developer.hashicorp.com/terraform/language/modules/develop/refactoring

What is the docs issue?

The Chapter "Removing moved Blocks" states "Removing a moved block is a generally breaking change because any configurations that refer to the old address will plan to delete that existing object instead of move it. We strongly recommend that you retain all historical moved blocks from earlier versions of your modules to preserve the upgrade path for users of any previous version." this wording is a bit confusing (We understand this that the moved blocks can never be removed) our interpretation does not seem to be true as after an apply (using moved in modules is a different story as every code using that module needs to be applied first before removing it) with the moved blocks we can safely remove the moved block as the state has been re-written.

Proposal

I'm not sure if this is an TFE only thing but IMO the docs should state something along the lines of this block can be removed after an apply has been done otherwise one would have a history if like 10 moved blocks as time goes on ?

Maybe something like this

"Removing a moved block can generally be considered a breaking change because configurations referencing the old address might plan to delete the existing object rather than move it. However, once the moved block has been applied and the state has been updated, it is safe to remove the block, as the state has been rewritten. We strongly recommend retaining historical moved blocks in earlier versions of your modules to ensure a smooth upgrade path for users of any previous version."

References

No response

[jbardin]

Hi @Netkracker,

The documentation is written for module authors who's modules are being consumed by an unknown number of users. The module author has no way to know what the condition of those user's Terraform state's are, and keeping the moved blocks ensures that any prior version of the state can be moved forward automatically with a new version of the module. Your proposed condition of when "the state has been updated" is not something all module authors can know.

The term "breaking change" does not mean it can never change, breaking changes are made all the time, but consideration must be taken with regard to appropriate semantic versioning and documentation.

[Netkracker]

hi @jbardin thx for you feedback, yes you are right about the modules but the docs do not only refer to modules though "In shared modules and long-lived configurations". These docs seem to be the only reference other then https://developer.hashicorp.com/terraform/language/moved (which states "Refer to Refactoring for details about how to use the moved block in your Terraform configurations." ) of the moved blocks from official sources ?

removing the moved blocks makes code way more readable especially when multiple breaking changes occur that would move infra multiple times. How would this even look like following the recommendation "We strongly recommend that you retain all historical moved blocks from earlier versions" if we apply this to root module configurations.

eg

move {
from = azurerm_linux_web_app.example
to = azurerm_linux_web_app.move1
}

move {
from = azurerm_linux_web_app.move1
to = azurerm_linux_web_app.move2
}

and so on ?

wdyt ?

[jbardin]

Yes, in root modules which you entirely control all use of this advice does not directly apply; you can manage those however you see fit. Semantically the intent of the term "breaking change" change still applies, but you have manually ensured all your states (which might only be 1) have moved past that change and the blocks can now be removed.

That documentation does already state:

It can be safe to remove moved blocks when you are maintaining private modules within an organization and you are certain that all users have successfully run terraform apply with your new module version.

Perhaps this can be reworded somehow?

[Netkracker]

hi @jbardin Sorry for the spam. The comment feature is giving me a headache because it seems I can't comment without closing the issue. (It's probably just me being dumb.)

i think that would be the right way ?

maybe something like

"When managing private modules within an organization, it can be safe to remove moved blocks after you have confirmed that all users have successfully run terraform apply with the new module version. While this approach can be applied in root modules that you fully control, it's important to note that the concept of a 'breaking change' still applies. However, if you have ensured that all your state files have progressed beyond the change, you can confidently remove those blocks."