"terraform plan" should produce an error when given a plan file

[eedwards-sk]

Terraform Version

v0.11.10

Terraform Configuration

s3 backend with terraform files containing aws data sources

Actual Behavior

running terraform plan <plan_name> updates the remote state

Expected Behavior

running terraform plan <plan_name> does not update the remote state

Steps to Reproduce

1. terraform init with s3 backend config (remote state file does not exist)
2. terraform plan -out=tfplan . (remote state file does not exist)
3. terraform plan tfplan (state file now exists)

Additional Context

running inside concourse ci pipeline

according to documentation, state should not be updated on a plan, e.g.:
https://www.terraform.io/guides/running-terraform-in-automation.html

Although the plan step updates the state to match real resources, thus ensuring an accurate plan, the updated state is not persisted, and so this command can safely be used to produce "throwaway" plans that are created only to aid in code review.

https://www.terraform.io/docs/commands/plan.html

This command is a convenient way to check whether the execution plan for a set of changes matches your expectations without making any changes to real resources or to the state.

I'm trying to use the terraform plan <plan_name> command to view an existing plan, so that an operator can confirm the changes

I want to use -refresh=true because the operator should know what the actual effects will be when ran

However, the state file should not be updated when viewing the plan, instead it should refresh and then 'throwaway' the state, correct?

[eedwards-sk]

Is there anything I can do to help surface this issue better?

As it stands, I cannot use "viewing planfiles" in my workflow, or I risk unintended changes to the remote state.

[apparentlymart]

Hi @eedwards-sk! Sorry for this strange behavior, and thanks for reporting it.

Passing an already-existing plan file to terraform plan is, I think, not something that is intentionally allowed but rather something that came as a consequence of how some code is shared between the various main Terraform commands. The behavior is, therefore, strange and unexpected. I expect the way we will resolve this issue is to make terraform plan tfplan generate an error, since that command doesn't really make sense within the intended Terraform workflow.

To view a plan file that was already created, you can use terraform show tfplan instead. That will just render the plan to the terminal, in a similar way to what terraform plan generated in the first place.

[eedwards-sk]

@apparentlymart

Thanks so much for the response and clarity over the workflow. I'm trying to build a CI pipeline with a 'view plan' step, so this was throwing quite the wrench in it. I'm excited to try the show command instead.

Generating an error when running against a plan file would definitely help, as would updating the docs on the plan command. That's where I mostly got set on this trail, specifically these two lines from https://www.terraform.io/docs/commands/plan.html:

Usage: terraform plan [options] [dir-or-plan]

If the command is given an existing saved plan as an argument, the command will output the contents of the saved plan. In this scenario, the plan command will not modify the given plan. This can be used to inspect a planfile.

Edit: also the output of terraform plan --help:

Usage: terraform plan [options] [DIR-OR-PLAN]

  Generates an execution plan for Terraform.

  This execution plan can be reviewed prior to running apply to get a
  sense for what Terraform will do. Optionally, the plan can be saved to
  a Terraform plan file, and apply can take this plan file to execute
  this plan exactly.

  If a saved plan is passed as an argument, this command will output
  the saved plan contents. It will not modify the given plan.

Thanks again.

[apparentlymart]

Thanks for pointing out the docs there. I'm not sure what is the story behind that; perhaps this used to be the way to do this prior to the implementation of the terraform show command and the docs have grown outdated.

I'm going to rescope this issue slightly to cover updating that documentation and removing what seems to be vestiges of an earlier usage that is no longer fully functional.

[apparentlymart]

From a quick inspection of the code, I see that the error message I mentioned is already in place in master ready to be included in the forthcoming v0.12.0 release:

terraform/command/plan.go

Lines 61 to 68 in f4cdb99

	if planFileReader != nil {
	c.showDiagnostics(tfdiags.Sourceless(
	tfdiags.Error,
	"Invalid configuration directory",
	fmt.Sprintf("Cannot pass a saved plan file to the 'terraform plan' command. To apply a saved plan, use: terraform apply %s", configPath),
	))
	return 1
	}

So the remaining work here is to get the docs updated. Since the behavior change here is already included in the v0.12.0 scope I'm going to add this issue to the v0.12.0 milestone to represent the need to update the docs as well before release.

[elliot-resdiary]

@apparentlymart

Passing an already-existing plan file to terraform plan is, I think, not something that is intentionally allowed but rather something that came as a consequence of how some code is shared between the various main Terraform commands.

The documentation for the plan command continues to state the following:

If the command is given an existing saved plan as an argument, the command will output the contents of the saved plan. In this scenario, the plan command will not modify the given plan. This can be used to inspect a planfile.

However, it seems this behavior was made unavailable in 0.12 and terraform show displays a lower resolution view of the plan than what's shown when the terraform plan command was run previously. Has this functionality been lost?

[ghost]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.