removed blocks do not cover all use cases of terraform state rm

[cam-mclaren]

Terraform Version

Terraform v1.8.5
on windows_amd64

Affected Pages

https://developer.hashicorp.com/terraform/cli/commands/state/rm
https://developer.hashicorp.com/terraform/language/resources/syntax#removing-resources

What is the docs issue?

The current issue with the documentation is that it is that the different use cases of terraform rm state and the removed blocks are not sufficiently highlighted. terraform rm state can remove a faulty object from a terraform state file which can be necessary if there are bugs in the remote platform for example or in a situation like that discussed here https://discuss.hashicorp.com/t/resource-manually-deleted-now-cant-destroy-plan-or-apply-due-to-it-missing-what-do/12215. On the other hand the removed blocks assume that a plan and the associated refresh action can be completed successfully. An object that is removed from the state file through a removed block requires that that object can be successfully refreshed as part of a terraform plan. As such removed blocks cannot help with all situations where terraform rm state is useful.

This is not discussed in the documentation. The different situations for why a user might want to "forget" a resource are not addressed. There may be cases where a user wishes to forget a resource because that resource is unresponsive to API calls. In such a case only terraform state rm will be useful. The removed block seems really only useful if the user wants to move an object out of terraforms configuration simply because they don't a particular terraform codebase to be responsible for managing that object. If there are errors on the remote platform removed may not be sufficient to remove the object from the configuration.

Proposal

I think the nuanced differences of terraform rm state with the removed blocks this should be discussed and the use cases they cover could be included here
I in particular I think the documentation could highlight that if a resource on a remote platform is unresponsive to the point it cannot even be refreshed successfully then removed blocks are not an adequate solution as they require a plan that refreshes the target objects state prior to it being dropped from the state file .

References

No response

[jbardin]

Hi @cam-mclaren,

Thanks for filing the issue. I think this would better be classified as a bug. The intent here is that the resource only be removed from the state, which does not require refreshing the resource at all. The refresh step is there because in the case of a normal delete operation, Terraform checks that the resource still exists before planning and skips the apply call when the resource has already been deleted externally (that should work either way, but providers have come to expect the current behavior). What's going on here is that while destroy = false skips applying the delete operation, it is failing to skip the refresh during the plan.