github.com/kanishk98/terraform@v1.3.0-dev.0.20220917174235-661ca8088a6a/website/docs/language/settings/backends/gcs.mdx (about)

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