hashicorp
terraform state -help makes incorrect claim about its output being for machines
Terraform Version
Terraform v1.2.0-beta1
on linux_amd64
Expected Behavior
From Terraform v1.0 onwards, our compatibility promises commit us to backward compatibility only with the explicitly-selected machine interfaces, and not to human-oriented output.
The intent of that commitment was to support the various situations where the caller explicitly requests machine readable output, via extra command line options like -json or -raw. It does not apply to any default output, even if that output happens to be relatively simple and amenable to line-based processing.
Actual Behavior
The terraform state -help output has a very stale old claim about the state commands being suitable for machine parsing:
$ terraform state -help
Usage: terraform [global options] state <subcommand> [options] [args]
This command has subcommands for advanced state management.
These subcommands can be used to slice and dice the Terraform state.
This is sometimes necessary in advanced cases. For your safety, all
state management commands that modify the state create a timestamped
backup of the state prior to making modifications.
The structure and output of the commands is specifically tailored to work
well with the common Unix utilities such as grep, awk, etc. We recommend
using those tools to perform more advanced state tasks.
(Notice the last paragraph above.)
I believe the original intent was not to encourage automation or scripting based on these results, but rather just to say that it might be helpful sometimes for humans to filter and process the output on a one-off basis in order to answer specific questions.
Regardless of original intent, this new message is not consistent with our current intentions, and so we should remove it altogether to avoid being confusing.
While we're there, we should probably also remove or adjust the last sentence of the penultimate paragraph, which makes a claim that these command always create a backup even though that has not been true for any non-local backend since Terraform v0.9.
Additional Context
Note that the main supported way to process the state programmatically is to run terraform show -json and then parse the resulting JSON output. That would be the most appropriate way to achieve anything that involves routine machine processing of Terraform state contents, and not any of the commands under the terraform state prefix.
(This was originally raised as part of #21779.)
While we're here (and thank you @apparentlymart for forking the issue):
I think the help text for terraform state [show] should explicitly mention that to get the state in a machine-readable format, you need to run terraform show, not terraform state show.
If one is browsing the commands provided by terraform, looking for something that would dump the state in a parseable form, finding the terraform state commands would easily lead one to assume that all state file related functions must live under the state top level command, and skip the show command. This was my experience at least.
(Of course, a user who's read the entire documentation before engaging with terraform might know better, but this approach is perhaps not very common in practice).
