backend/remote-state/gcs: Document the "prefix" option.

"state_dir" has been renamed to "prefix" to better fix the GCS
terminology.

backend/remote-state/gcs/backend.go

@@ -25,7 +25,7 @@ type gcsBackend struct {
 	storageContext context.Context
 
 	bucketName       string
-	stateDir         string
+	prefix           string
 	defaultStateFile string
 }
 
@@ -43,10 +43,10 @@ func New() backend.Backend {
 			"path": {
 				Type:        schema.TypeString,
 				Optional:    true,
-				Description: "(Legacy) Path of the default state file; use state_dir instead",
+				Description: "(Legacy) Path of the default state file; use prefix instead",
 			},
 
-			"state_dir": {
+			"prefix": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				Description: "The directory where state files will be saved inside the bucket",
@@ -78,7 +78,7 @@ func (b *gcsBackend) configure(ctx context.Context) error {
 	data := schema.FromContextBackendConfig(b.storageContext)
 
 	b.bucketName = data.Get("bucket").(string)
-	b.stateDir = strings.TrimLeft(data.Get("state_dir").(string), "/")
+	b.prefix = strings.TrimLeft(data.Get("prefix").(string), "/")
 
 	b.defaultStateFile = strings.TrimLeft(data.Get("path").(string), "/")
 

backend/remote-state/gcs/backend_state.go

@@ -27,7 +27,7 @@ func (b *gcsBackend) States() ([]string, error) {
 	bucket := b.storageClient.Bucket(b.bucketName)
 	objs := bucket.Objects(b.storageContext, &storage.Query{
 		Delimiter: "/",
-		Prefix:    b.stateDir,
+		Prefix:    b.prefix,
 	})
 	for {
 		attrs, err := objs.Next()
@@ -144,12 +144,12 @@ func (b *gcsBackend) stateFile(name string) string {
 	if name == backend.DefaultStateName && b.defaultStateFile != "" {
 		return b.defaultStateFile
 	}
-	return path.Join(b.stateDir, name+stateFileSuffix)
+	return path.Join(b.prefix, name+stateFileSuffix)
 }
 
 func (b *gcsBackend) lockFile(name string) string {
 	if name == backend.DefaultStateName && b.defaultStateFile != "" {
 		return strings.TrimSuffix(b.defaultStateFile, stateFileSuffix) + lockFileSuffix
 	}
-	return path.Join(b.stateDir, name+lockFileSuffix)
+	return path.Join(b.prefix, name+lockFileSuffix)
 }

backend/remote-state/gcs/backend_test.go

@@ -6,7 +6,7 @@ import (
 
 func TestStateFile(t *testing.T) {
 	cases := []struct {
-		stateDir         string
+		prefix           string
 		defaultStateFile string
 		name             string
 		wantStateFile    string
@@ -21,7 +21,7 @@ func TestStateFile(t *testing.T) {
 	}
 	for _, c := range cases {
 		b := &gcsBackend{
-			stateDir:         c.stateDir,
+			prefix:           c.prefix,
 			defaultStateFile: c.defaultStateFile,
 		}
 

website/docs/backends/types/gcs.html.md

@@ -8,18 +8,18 @@ description: |-
 
 # gcs
 
-**Kind: Standard (with no locking)**
+**Kind: Standard (with locking)**
 
-Stores the state as a given key in a given bucket on [Google Cloud Storage](https://cloud.google.com/storage/).
+Stores the state as an object in a configurable prefix and bucket on [Google Cloud Storage](https://cloud.google.com/storage/) (GCS).
 
 ## Example Configuration
 
 ```hcl
 terraform {
   backend "gcs" {
-    bucket  = "tf-state-prod"
-    path    = "path/terraform.tfstate"
     project = "myproject"
+    bucket  = "tf-state-prod"
+    prefix  = "terraform/state"
   }
 }
 ```
@@ -30,9 +30,9 @@ terraform {
 data "terraform_remote_state" "foo" {
   backend = "gcs"
   config {
-    bucket  = "terraform-state-prod"
-    path    = "network/terraform.tfstate"
     project = "goopro"
+    bucket  = "terraform-state"
+    prefix  = "prod"
   }
 }
 
@@ -49,6 +49,7 @@ resource "template_file" "bar" {
 
 The following configuration options are supported:
 
- * `bucket` - (Required) The name of the GCS bucket
- * `path` - (Required) The path where to place/look for state file inside the bucket
- * `credentials` / `GOOGLE_CREDENTIALS` - (Required) Google Cloud Platform account credentials in json format
+ * `bucket` - (Required) The name of the GCS bucket.
+ * `credentials` / `GOOGLE_CREDENTIALS` - (Required) Local path to Google Cloud Platform account credentials in JSON format.
+ * `prefix` - (Optional) GCS prefix inside the bucket. Named states are stored in an object called `<prefix>/<name>.tfstate`.
+ * `path` - (Legacy) GCS path to the state file of the default state. For backwards compatibility only, use `prefix` instead.