---
page_title: 'Backend Type: gcs'
description: >-
  Terraform can store the state remotely, making it easier to version and work
  with in a team.
---

# gcs

Stores the state as an object in a configurable prefix in a pre-existing bucket on [Google Cloud Storage](https://cloud.google.com/storage/) (GCS).
The bucket must exist prior to configuring the backend.

This backend supports [state locking](/language/state/locking).

~> **Warning!** It is highly recommended that you enable
[Object Versioning](https://cloud.google.com/storage/docs/object-versioning)
on the GCS bucket to allow for state recovery in the case of accidental deletions and human error.

## Example Configuration

```hcl
terraform {
  backend "gcs" {
    bucket  = "tf-state-prod"
    prefix  = "terraform/state"
  }
}
```

## Data Source Configuration

```hcl
data "terraform_remote_state" "foo" {
  backend = "gcs"
  config = {
    bucket  = "terraform-state"
    prefix  = "prod"
  }
}

resource "template_file" "bar" {
  template = "${greeting}"

  vars {
    greeting = "${data.terraform_remote_state.foo.greeting}"
  }
}
```

## Authentication

IAM 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.

### Running Terraform on your workstation.

If you are using terraform on your workstation, you will need to install the Google Cloud SDK and authenticate using [User Application Default
Credentials](https://cloud.google.com/sdk/gcloud/reference/auth/application-default).

User ADCs do [expire](https://developers.google.com/identity/protocols/oauth2#expiration) and you can refresh them by running `gcloud auth application-default login`.

### Running Terraform on Google Cloud

If you are running terraform on Google Cloud, you can configure that instance or cluster to use a [Google Service
Account](https://cloud.google.com/compute/docs/authentication). This will allow Terraform to authenticate to Google Cloud without having to bake in a separate
credential/authentication file. Make sure that the scope of the VM/Cluster is set to cloud-platform.

### Running Terraform outside of Google Cloud

If you are running terraform outside of Google Cloud, generate a service account key and set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to
the path of the service account key. Terraform will use that key for authentication.

### Impersonating Service Accounts

Terraform 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.

## Configuration variables

The following configuration options are supported:

- `bucket` - (Required) The name of the GCS bucket.  This name must be
  globally unique.  For more information, see [Bucket Naming
  Guidelines](https://cloud.google.com/storage/docs/bucketnaming.html#requirements).
- `credentials` / `GOOGLE_BACKEND_CREDENTIALS` / `GOOGLE_CREDENTIALS` -
  (Optional) Local path to Google Cloud Platform account credentials in JSON
  format.  If unset, [Google Application Default
  Credentials](https://developers.google.com/identity/protocols/application-default-credentials)
  are used.  The provided credentials must have Storage Object Admin role on the bucket.
  **Warning**: if using the Google Cloud Platform provider as well, it will
  also pick up the `GOOGLE_CREDENTIALS` environment variable.
- `impersonate_service_account` - (Optional) The service account to impersonate for accessing the State Bucket.
  You must have `roles/iam.serviceAccountTokenCreator` role on that account for the impersonation to succeed.
  If you are using a delegation chain, you can specify that using the `impersonate_service_account_delegates` field.
  Alternatively, this can be specified using the `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT` environment
  variable.
- `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).
- `access_token` - (Optional) A temporary \[OAuth 2.0 access token] obtained
  from the Google Authorization server, i.e. the `Authorization: Bearer` token
  used to authenticate HTTP requests to GCP APIs. This is an alternative to
  `credentials`. If both are specified, `access_token` will be used over the
  `credentials` field.
- `prefix` - (Optional) GCS prefix inside the bucket. Named states for
  workspaces are stored in an object called `<prefix>/<name>.tfstate`.
- `encryption_key` / `GOOGLE_ENCRYPTION_KEY` - (Optional) A 32 byte base64
  encoded 'customer supplied encryption key' used to encrypt all state. For
  more information see [Customer Supplied Encryption
  Keys](https://cloud.google.com/storage/docs/encryption#customer-supplied).