Clarify use of backend-config file

[asmacdo]

-backend-config It is not a "full override" as one might expect. It works only within the context of an existing partial configuration.

I'm not confident that my docs changes are exactly correct-- but hopefully this will make things a little clearer. I realize this is within the "Partial Configuration" section, but I still found the behavior a little surprising.

(Why do I need to do this? I am using multiple tf environments, which must store their state separately.)

I (as suggested by a confused ChatGPT) attempted:

terraform init -backend-config myfile.tf

myfile.tf

terraform {
  backend "s3" {
    bucket =  "mybucket"
    key = "terraform.tfstate"
    region = "us-east-2"
    encrypt = true
    dynamodb_table = "my-tf-lock"
  }
}

IMO this seems like a pretty reasonable expectation. I did receive a warning that it wasn't overriding any specific config, but I thought that seemed ok. What I absolutely did not expect was that tf would proceed and store my tfstate locally.

The helptext was a little more helpful.

  -backend-config=path    Configuration to be merged with what is in the
                          configuration file's 'backend' block. This can be
                          either a path to an HCL file with key/value
                          assignments (same format as terraform.tfvars) or a
                          'key=value' format, and can be specified multiple
                          times. The backend type must be in the configuration
                          itself.

What ended up working for me:

backend.tf

terraform {
  backend "s3" {
    # NOTHING
  }
}

terraform init -backend-config myfile.tf

myfile.tf

bucket =  "mybucket"
key = "terraform.tfstate"
region = "us-east-2"
encrypt = true
dynamodb_table = "my-tf-lock"

[hashicorp-cla-app]

All committers have signed the CLA.

[crw]

Thanks for this submission!

[asmacdo]

@crw Do you think this contribution is worth keeping? I'm happy to resolve conflicts, or we can close if this isnt helpful.

[crw]

Hi @asmacdo, let me check with the docs team. I think this may have been misplaced due to some changes in how we were working with documentation changes.

[trujillo-adam]

Added some suggestions to improve the clarity and style.

[trujillo-adam]

Suggested change

	- Using a backend configuration file or CLI key-value pairs overrides the contents,
	but not the type of `backend`. (e.g. Use a Partial Configuration in the primary config.)
	You can use the `-backend-config` flag on the CLI to provide a backend configuration. You can either specify a file containing a partial configuration or specify a set of key-value pairs. Terraform applies the configurations to the arguments in the `backend` block, but it does not change the type. In the following example, Terraform stores state in the default backend using the arguments supplied in the `-backend-config` flag:

I think this is the point you are making?

[asmacdo]

Yes but it does miss one of the key things I wanted to document. I was surprised when trying to use this that I needed a partial configuration in the primary config, I guessed I could have just provided the backend from scratch in the override.

[github-actions]

Changelog Warning

Currently this PR would target a v1.12 release. Please add a changelog entry for in the .changes/v1.12 folder, or discuss which release you'd like to target with your reviewer. If you believe this change does not need a changelog entry, please add the 'no-changelog-needed' label.