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