Previously the "terraform state ..." subcommands were the only way to
perform various manipulations of the state, but in recent Terraform
versions we have replaced these with better options.
Since these pages seem to already have pretty good search engine
optimization for the use-cases they are describing, we'll prioritize
mentioning the new approaches and only mention the now-deprecated or
de-emphasized features as a secondary approach.
Specifically:
- Describe the -replace=... planning option in preference to
"terraform taint", and present taint as primarily a mechanism for
Terraform to use itself, as opposed to something end-users should
typically use directly.
- Introduce the config-based refactoring features before describing
"terraform state mv".
The older features here are still applicable in some situations and are
required for those still using older versions of Terraform, so we will
retain the information about them for now while aiming to be clearer in
each case about which is our preferred, modern approach.
It's been a long time since we gave this page an overhaul, and with our
ongoing efforts to make plan and apply incorporate all of the side-effects
that might need to be done against a configuration it seems like a good
time for some restructuring in that vein.
The starting idea here is to formally split the many "terraform plan"
options into a few different categories:
- Planning modes
- Planning options
- Other options
The planning modes and options are the subset that are also accepted by
"terraform apply" when it's running in its default mode of generating a
plan and then prompting for interactive approval of it. This then allows
us to avoid duplicating all of that information on the "terraform apply"
page, and thus allows us to spend more words discussing each of them.
This set of docs is intended as a fresh start into which we'll be able to
more surgically add in the information about -refresh-only and -replace=...
once we have those implemented. Consequently there are some parts of this
which may seem a little overwraught for what it's currently describing;
that's a result of my having prepared this by just deleting the
-refresh-only and -replace=... content from our initial docs draft and
submitted the result, in anticipation of re-adding the parts I've deleted
here in the very near future in other commits.
The new nav structure demanded a few new pages that give context about a feature
or workflow. In a few cases, they take text from an existing page.
Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
Co-authored-by: Judith Malnick <judith.patudith@gmail.com>
Martin Atkins