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