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.
Thank you. Your suggestion to use "instead of" makes the sentence even more easy to understand.
Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
We recently made a change to how provisioners upload files in order to
address an unintended remote code execution vector when using SSH, which
revealed that we had not previously documented well enough the expected
contract for how provisioners upload files to remote systems, and so some
users were depending on unintended consequences of the the bug now fixed.
We are retaining the fix on security-related grounds, but this is a good
prompt to be clearer in the docs about what exactly Terraform is doing
when asked to upload files over SSH and WinRM, so users can understand
what is supported and write their configurations accordingly.
This also includes an additional section to the v1.1 upgrade guide, since
we apparently neglected to document this intentional breaking change in
the first draft of that page.
Of course, provisioners as a whole remain a last resort, and so we're
documenting this as hopefully a helpful aid to those who have no other
option, and not meaning in any way to recommend their use for any new
use-cases.
Laura Pacilio