terraform state -help makes incorrect claim about its output being for machines
Terraform Version
Terraform v1.2.0-beta1
on linux_amd64Expected 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.)
Source: hashicorp/terraform