1--- 2layout: "language" 3page_title: "Backend Type: gcs" 4sidebar_current: "docs-backends-types-standard-gcs" 5description: |- 6 Terraform can store the state remotely, making it easier to version and work with in a team. 7--- 8 9# gcs 10 11**Kind: Standard (with locking)** 12 13Stores the state as an object in a configurable prefix in a pre-existing bucket on [Google Cloud Storage](https://cloud.google.com/storage/) (GCS). 14This backend also supports [state locking](/docs/language/state/locking.html). The bucket must exist prior to configuring the backend. 15 16~> **Warning!** It is highly recommended that you enable 17[Object Versioning](https://cloud.google.com/storage/docs/object-versioning) 18on the GCS bucket to allow for state recovery in the case of accidental deletions and human error. 19 20## Example Configuration 21 22```hcl 23terraform { 24 backend "gcs" { 25 bucket = "tf-state-prod" 26 prefix = "terraform/state" 27 } 28} 29``` 30 31## Data Source Configuration 32 33```hcl 34data "terraform_remote_state" "foo" { 35 backend = "gcs" 36 config = { 37 bucket = "terraform-state" 38 prefix = "prod" 39 } 40} 41 42resource "template_file" "bar" { 43 template = "${greeting}" 44 45 vars { 46 greeting = "${data.terraform_remote_state.foo.greeting}" 47 } 48} 49``` 50 51## Authentication 52 53IAM Changes to buckets are [eventually consistent](https://cloud.google.com/storage/docs/consistency#eventually_consistent_operations) and may take upto a few minutes to take effect. Terraform will return 403 errors till it is eventually consistent. 54 55### Running Terraform on your workstation. 56 57If you are using terraform on your workstation, you will need to install the Google Cloud SDK and authenticate using [User Application Default 58Credentials](https://cloud.google.com/sdk/gcloud/reference/auth/application-default). 59 60User ADCs do [expire](https://developers.google.com/identity/protocols/oauth2#expiration) and you can refresh them by running `gcloud auth application-default login`. 61 62### Running Terraform on Google Cloud 63 64If you are running terraform on Google Cloud, you can configure that instance or cluster to use a [Google Service 65Account](https://cloud.google.com/compute/docs/authentication). This will allow Terraform to authenticate to Google Cloud without having to bake in a separate 66credential/authentication file. Make sure that the scope of the VM/Cluster is set to cloud-platform. 67 68### Running Terraform outside of Google Cloud 69 70If you are running terraform outside of Google Cloud, generate a service account key and set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to 71the path of the service account key. Terraform will use that key for authentication. 72 73### Impersonating Service Accounts 74 75Terraform can impersonate a Google Service Account as described [here](https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials). A valid credential must be provided as mentioned in the earlier section and that identity must have the `roles/iam.serviceAccountTokenCreator` role on the service account you are impersonating. 76 77## Configuration variables 78 79The following configuration options are supported: 80 81 * `bucket` - (Required) The name of the GCS bucket. This name must be 82 globally unique. For more information, see [Bucket Naming 83 Guidelines](https://cloud.google.com/storage/docs/bucketnaming.html#requirements). 84 * `credentials` / `GOOGLE_BACKEND_CREDENTIALS` / `GOOGLE_CREDENTIALS` - 85 (Optional) Local path to Google Cloud Platform account credentials in JSON 86 format. If unset, [Google Application Default 87 Credentials](https://developers.google.com/identity/protocols/application-default-credentials) 88 are used. The provided credentials must have Storage Object Admin role on the bucket. 89 **Warning**: if using the Google Cloud Platform provider as well, it will 90 also pick up the `GOOGLE_CREDENTIALS` environment variable. 91 * `impersonate_service_account` - (Optional) The service account to impersonate for accessing the State Bucket. 92 You must have `roles/iam.serviceAccountTokenCreator` role on that account for the impersonation to succeed. 93 If you are using a delegation chain, you can specify that using the `impersonate_service_account_delegates` field. 94 Alternatively, this can be specified using the `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT` environment 95 variable. 96 * `impersonate_service_account_delegates` - (Optional) The delegation chain for an impersonating a service account as described [here](https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials#sa-credentials-delegated). 97 * `access_token` - (Optional) A temporary [OAuth 2.0 access token] obtained 98 from the Google Authorization server, i.e. the `Authorization: Bearer` token 99 used to authenticate HTTP requests to GCP APIs. This is an alternative to 100 `credentials`. If both are specified, `access_token` will be used over the 101 `credentials` field. 102 * `prefix` - (Optional) GCS prefix inside the bucket. Named states for 103 workspaces are stored in an object called `<prefix>/<name>.tfstate`. 104 * `encryption_key` / `GOOGLE_ENCRYPTION_KEY` - (Optional) A 32 byte base64 105 encoded 'customer supplied encryption key' used to encrypt all state. For 106 more information see [Customer Supplied Encryption 107 Keys](https://cloud.google.com/storage/docs/encryption#customer-supplied). 108