5.2 KiB
layout | page_title | sidebar_current | description |
---|---|---|---|
language | Backend Type: gcs | docs-backends-types-standard-gcs | Terraform can store the state remotely, making it easier to version and work with in a team. |
gcs
Kind: Standard (with locking)
Stores the state as an object in a configurable prefix in a pre-existing bucket on Google Cloud Storage (GCS). This backend also supports state locking. The bucket must exist prior to configuring the backend.
~> Warning! It is highly recommended that you enable Object Versioning on the GCS bucket to allow for state recovery in the case of accidental deletions and human error.
Example Configuration
terraform {
backend "gcs" {
bucket = "tf-state-prod"
prefix = "terraform/state"
}
}
Data Source Configuration
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 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.
User ADCs do expire 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. 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_APPPLICATION_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. 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.credentials
/GOOGLE_BACKEND_CREDENTIALS
/GOOGLE_CREDENTIALS
- (Optional) Local path to Google Cloud Platform account credentials in JSON format. If unset, Google 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 theGOOGLE_CREDENTIALS
environment variable.impersonate_service_account
- (Optional) The service account to impersonate for accessing the State Bucket. You must haveroles/iam.serviceAccountTokenCreator
role on that account for the impersonation to succeed. If you are using a delegation chain, you can specify that using theimpersonate_service_account_delegates
field. Alternatively, this can be specified using theGOOGLE_IMPERSONATE_SERVICE_ACCOUNT
environment variable.impersonate_service_account_delegates
- (Optional) The delegation chain for an impersonating a service account as described here.access_token
- (Optional) A temporary [OAuth 2.0 access token] obtained from the Google Authorization server, i.e. theAuthorization: Bearer
token used to authenticate HTTP requests to GCP APIs. This is an alternative tocredentials
. If both are specified,access_token
will be used over thecredentials
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.