website: First draft of "Refactoring" documentation, about "moved" blocks

[apparentlymart]

This is an early iteration of documentation about the refactoring features we're intending to introduce in a forthcoming release.

I've named the documentation section "refactoring" because in previous discussions with users that seems to be the term they use to describe the underlying need. moved blocks are our first language feature intended to meet that need, although it probably won't be the last as we consider other requirements in later releases. My intent here is that once we've published this it should eventually end up being the first result for a web search for the topic of Terraform refactoring.

[laurapacilio]

Hello! 👋

I'm going to do a more thorough review of the drafted content, but one thing for us to consider as part of this PR is whether there are other pages within the docs where we'd want to link to or reference this new information. For example: Could we add a bullet on the modules development overview page? What about on the module blocks page (just a bit of context and a pointer to the refactoring page)?

Also - I'm wondering about this article's position in the hierarchy. Is this something that module creators would need to do within their module's configuration so that their changes don't affect folks who are calling their module? or is this something that folks who are calling an updated/moved child module would need to do in their configuration? Both? The reason I ask is - Should this be housed in the module development section instead? We can always do good cross-linking, wherever the page ends up being located, but wanted to put this out there.

[apparentlymart]

Thanks for those initial thoughts, @laurapacilio!

I honestly hadn't noticed that we'd broken out "Module Development" into a separate category here, and now I know about it I agree that it makes more sense for this content to live there. As you suspected, this is primarily a feature for module developers to do refactoring without disrupting their callers.

Folks who are only using modules will only interact with it in the limited sense that the Terraform plan UI will include some mention that an object was moved, which might call for us having some other documentation somewhere to talk about that from the caller's perspective, but I'm optimistically hoping that the UI will be intuitive enough for most folks that we won't need to spend too many words on it in the docs.

I think our overall distinction between module usage and module development is still a bit shaky here, as a result of us only recently starting to formalize that distinction. For that reason I feel unsure where would be best to link to this page; it seems like a tricky one because it's something that many folks will never actually need to know about, and even once they do I'm not sure they'd expect to find a language feature for it, and so I'd expected they'd be more likely to use a search engine for a general term like "terraform refactoring" and then hopefully turn this up as the first result. With that said, the overview of the Module Development section (currently titled Creating Modules) seems like a short enough page that it wouldn't hurt to add a little about refactoring to it, perhaps as an additional paragraph under the "Module structure" section.

I'm going to be away from work for a little while over the next couple weeks so I expect I won't have time to do revisions here until I get back, but I agree with all of this feedback so far and do intend to incorporate it. Thanks!

[laurapacilio]

This is really great Martin! I know you're still working on this, but I made a couple more nit suggestions for flow.

[laurapacilio]

Maybe this is obvious for folks, but I feel like I'm missing one more sentence after this about why this is a good thing. Does it save time and money?

Suggested change

	You can use `moved` blocks in your configuration to record where you've
	historically moved or renamed an object, in which case Terraform will instead
	treat an existing object at the old address as if it now belongs to the new
	address.
	When you add `moved` blocks in your configuration to record where you've historically moved or renamed an object, Terraform will instead treat an existing object at the old address as if it now belongs to the new address.

[apparentlymart]

Good point!

I think the "why is this good" can vary between situations, so I'll have a think about how to write this in a more concise way, but in the interests of capturing the answer somewhere we can refer to it for later edits, reasons might include:

• As you suggested, it could be time-consuming to destroy and recreate some kinds of objects.
• The brief period where there are fewer (or no) objects of a particular type, or in some cases too many objects of a particular type (if we're using create_before_destroy) can potentially cause total downtime or problematic backpressure on other subsystems. For example, adding new members to a Consul cluster will cause the cluster to temporarily thrash as it replicates data from the existing servers to the new servers, which might hurt performance for systems depending on that cluster.
• Some objects are not trivially replaceable. For example, if we have a resource representing a database server and we replace the database server then we'll probably be replacing a server which has data in it with a server that has no data in it.

Perhaps the general way to talk about this is the idea that there are lots of infrastructure object types where replacing them requires careful planning and possibly coordination with other teams, and so module users and authors would typically prefer that just upgrading to a new version of a module (without making other changes) would not involve replacing any existing objects.

I'll continue to ponder this, though if what I've said here gives you any ideas about how to word this then of course I'd love to hear them!

[laurapacilio]

I will think about this, too! Thank you as always for the awesome explanation :-)

[apparentlymart]

I've incorporated most of the feedback from above exactly as written. Thanks!

I resolved all of the ones I just incorporated directly so it's easier to see what's left; I had a few questions about how to proceed with some of the less obvious situations.

[laurapacilio]

Adding in a few more comments to address "imagine" language. I agree that this is a construction that we want to avoid. I think instead, the "Consider this example module" language is better. It's short, and the word "example" helps the user know that we're about to walk through something. And then, I try to make things as clean and simple as possible as the scenario evolves. For example rather than "If later requirements need you to X" we can say "Later, you X". Let me know if that doesn't make sense/if you want to talk about it more.

[apparentlymart]

We do have a few little things dangling above but it feels to me like this is in reasonable shape for the first release of this feature. Would you agree, @laurapacilio?

I'm going to hold on merging this until the actual implementation is far enough along that we remove its experimental feature warnings in the UI, because it'd be confusing to publish this anywhere while the implementation work is still not complete, so we do have some time for further editing but unless you object I'm going to plan to merge this once the time is right, so we can make sure it's in place in time for releasing the feature. We can continue to update it once we've published it, if we need to, of course.

Thanks again for all of the suggestions!

[laurapacilio]

I do agree! Thanks for working with me on this - I definitely think it's ready for the first release. Great job, Martin - ship it when ready! 🚀

[korinne]

This is great documentation! I have one item for feedback: Could we add more prescriptive guidance around removing moved blocks? I'm certain we're going to (and internally already have) a lot of questions about how to best do this. The content is all there, but it might need better framing. Something like:

To remove moved blocks, this is what we recommend:

1. For private module maintainers: it's safe to remove moved blocks in laters versions of your module as long as you know that all module users have successfully run terraform apply with your new module version. However, ... [list any caveats plus an example]
2. Any recommendations we have against removing moved blocks.

I mainly want us to provide guardrails for users to know when it's safe to do something, and when we'd advise against it.

[apparentlymart]

Thanks for the feedback, @korinne! @laurapacilio, do you have some ideas about how we might restructure the final section of the page ("Removing moved Blocks") to emphasize the information as Korinne is suggesting? Might we need to explicitly separate the advice for in-house-only vs. shared modules to help readers navigate to the advice that's most relevant to them? 🤔

[laurapacilio]

I left a suggestion about how we might give stronger advice about removing moved blocks, per @korinne's comment! See what you think! I think you could add one more sentence (as korinne suggested) after the section about "if you do decide to remove moved blocks...." that kind of reiterates a warning or any other considerations users should think about before doing this. Let me know if you think this is better! But now we're leading with our recommendation, phrasing things more strongly, and hopefully making it clearer what users really should and shouldn't do here.

[apparentlymart]

Unfortunately this website-link-check failure has been showing up in a bunch of places and isn't directly related to this changeset. It seems like the container image we use for that job might need updating to include a fresher set of CA certificates in order to actually trust the certs on the external sites we're linking to, but we'll need to tackle that elsewhere.

[laurapacilio]

Yes! I believe folks are working on these :-) hashicorp/terraform-website#1925

Don't let those be a blocker to merge this if you need to!

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.