How to specify a state file name in terraform backend?

Question

I created a terraform gcs backend using the block :

 terraform {
  backend "gcs" {
    bucket                      = "<redacted_bucket_name>"
    prefix                      = "base/terraform.state"
    impersonate_service_account = "<redacted_service_account>@<redacted_project_id>.iam.gserviceaccount.com"
  }
}

By performing a terraform init, this creates the state file in the specified bucket but in a directory :

<bucket>
|--base (Directory)
  |--terraform.state (Directory)
    |--default.state (File)

How do I specify the name of the state file? I know I've used the prefix wrong in this example, but there is nothing in the documentation about it.

Answer 1

The name is the name of the Terraform workspace that you're working in (hence default).

You use workspaces to separate your deployments when you're using the same code for multiple environments.

For example, if you were to perform a terraform init with a backend configured, it would use the default workspace and create a default.tfstate within the bucket.

If you were to do a terraform workspace new prod and performed a terraform init you would be working against a state file of prod.tfstate.

You don't have to use workspaces though as they can add complexity to the pipeline. You could just as easily have a different backend or place the state file under a different prefix; you can think of prefix in regards to GCS backends as a directory structure to place the state file.

e.g. prefix=terraform/myproject/nonprod would keep a default.tfstate under a nonprod directory so it's separate from the other environments. Whatever works for you.

prefix - (Optional) GCS prefix inside the bucket. Named states for workspaces are stored in an object called /.tfstate.

source