Terraform on Google Cloud

The provider ships a numbered upgrade guide for every major version. The guides say, in the same words each time, to upgrade to the last release of the previous major first, fix every deprecation warning, run terraform plan until it is clean, and only then raise the constraint. They also explain how to go back: if you ran only init or plan, downgrading the provider is enough; after refresh or apply, restore the previous state version from a versioned backend such as the gcs bucket described below.

Source: Version 6 upgrade guide, Version 7 upgrade guide and Version 8 upgrade guide

The 7.x series still receives patches, and the Cloud Foundation Toolkit modules accept both 7 and 8 (their constraint is >= 4.64, < 9 for the network module), so a staged upgrade is realistic. The Cloud Foundation Fabric modules, on the other hand, require >= 8.6.0, < 9.0.0 in their current release. Combine modules from both collections only after checking that their provider ranges overlap.

On a workstation, install the Google Cloud CLI, run gcloud init, and create the ADC file once. Nothing is written into the Terraform directory.

Source: Google Cloud — Authentication for Terraform

A person should not run production changes with their own broad permissions. The usual pattern is to give each environment a deployer service account that holds the roles Terraform needs, and to let a small group of people (and the CI identity) act as it. Terraform then runs as that account while the caller’s own identity only needs one role on it, roles/iam.serviceAccountTokenCreator. Permissions and quotas are evaluated against the impersonated account. You can configure it in three equivalent ways:

Source: Terraform Registry — google_service_account and google_service_account_iam

Source: Google Provider Configuration Reference — Impersonating Service Accounts and google_service_account_iam

The provider reference also describes a variation worth knowing: an ephemeral access token. The google_service_account_access_token ephemeral resource mints a short-lived token for a target service account, and a second, aliased google provider block can take it as access_token. The token never reaches the state or the plan, which makes it a good fit when one configuration must act as several service accounts. Because Terraform cannot renew an access token, a very long apply can outlive it (the default lifetime is one hour), and the documentation recommends credentials that can be refreshed in that case.

Source: Terraform Registry — google_service_account_access_token (ephemeral)

A pipeline running on GitHub, GitLab or another OIDC issuer should not hold a service account key. Instead, Google Cloud trusts the issuer through a workload identity pool and a provider in that pool, and the pipeline exchanges its short-lived OIDC token for Google credentials. The Terraform resources for the pool and provider (google_iam_workload_identity_pool, google_iam_workload_identity_pool_provider) and the roles/iam.workloadIdentityUser binding, together with the mandatory attribute condition that stops other repositories from using the trust, are shown in the Google Cloud part of CI/CD and Automation, and the Google Cloud side of the concept is explained in Identity and Access. They are not repeated here.

What belongs on this page is how the resulting credentials meet Terraform. The google-github-actions/auth action (major version 3 at the time of writing) exchanges the OIDC token and, by default, writes a credentials file and exports GOOGLE_APPLICATION_CREDENTIALS. Both the provider and the gcs backend read ADC, so no further Terraform configuration is needed. The workflow needs id-token: write, and the checkout step must run before the auth step.

Source: google-github-actions/auth README, actions/checkout and hashicorp/setup-terraform

With service_account set, the action uses federation through a service account, which needs roles/iam.workloadIdentityUser on it; without it, it uses direct federation and the pool principal itself receives roles on the resources. The action’s README warns that the GitHub token lives five minutes, so derived credentials last five minutes too, and that changes to pools and providers can take a few minutes to propagate.

The provider also supports federation without a credentials file. Its external_credentials block (added in 6.28.0) takes an audience, a service_account_email and an identity_token, builds a federated credential from the token, and takes precedence over credentials and access_token. It was designed for HCP Terraform Stacks, where the platform hands the configuration an identity token, and the provider has a guide for that case; see Terraform Stacks. Like an access token, the credential built from it cannot be renewed, and the documentation suggests a credentials file with a federation configuration for runs that last longer than the token.

The chicken-and-egg problem has a simple resolution, which Google’s own tutorial uses: create the bucket with a small configuration that has a local backend, add the gcs backend block afterwards, and run terraform init -migrate-state to move the state into the bucket. Many teams keep this bootstrap configuration in its own repository or directory and keep its state in the bucket it created, or accept that it has a local state that is stored with the platform team’s documentation; either choice is fine as long as it is deliberate. The gcloud equivalent is in Infrastructure as Code on Google Cloud.

A state bucket has requirements that ordinary buckets do not: only the pipeline and a few administrators may touch it, object versions must be kept (with a cap, because every apply writes a new version), the bucket must not be deletable by mistake, and public access must be impossible.

Source: Terraform Registry — google_storage_bucket and Google Cloud — Store Terraform state in a Cloud Storage bucket

In the provider’s schema uniform_bucket_level_access defaults to false and public_access_prevention to inherited, so both must be set explicitly for a hardened bucket. The soft_delete_policy block is optional and computed: leaving it out keeps whatever the service decides, and a value of 0 for retention_duration_seconds disables soft delete. Cloud Storage’s own documentation explains that versioning and soft delete have different costs; the lifecycle rule above limits the former. The num_newer_versions condition cannot be set to 0 from Terraform, as the provider documents.

The workflow to adopt the bucket afterwards is:

Source: Terraform Docs — terraform init

The -migrate-state flag is the supported way to move state between backends. Older tutorials, including the book that motivates this page, suggest state pull and state push, which the documentation describes as dangerous and unnecessary for this job.

The terraform_remote_state data source can read a gcs state, as Google’s root-module guidance suggests when a network project exposes values to application projects. It needs read access to the whole state, which includes secrets, so prefer to expose only what is necessary through the producer’s outputs, and consider the alternatives (data sources, or publishing values to a parameter store) discussed in Backends and Remote State.

Source: Terraform Docs — Backend type: gcs and Terraform Docs — The terraform_remote_state data source

OpenTofu documents the same backend with one more argument, universe_domain (and the environment variables GOOGLE_BACKEND_UNIVERSE_DOMAIN and GOOGLE_CLOUD_UNIVERSE_DOMAIN), used together with a private endpoint for sovereign or partner clouds. OpenTofu can also encrypt state and plan files client side before they reach the bucket, which Terraform cannot do; see State and OpenTofu.

Infra Manager imposes rules that ordinary Terraform does not:

The version list has direct consequences for how you write the code. Everything introduced after Terraform 1.5 is out of reach: ephemeral resources, write-only arguments (1.10 and 1.11), provider-defined functions, removed blocks (1.7), and terraform test (1.6) do not apply, and a module that declares a required_version of >= 1.12.2, which is what the Cloud Foundation Fabric modules do, cannot be used at all. The Cloud Foundation Toolkit network module, whose requirement is >= 1.3, can. Infra Manager can also use either the HashiCorp-maintained provider (the default) or a service-maintained copy of google and google-beta, selected with --provider-source=SERVICE_MAINTAINED; the supported provider versions per region are listed in a manifest.json in a Google-maintained bucket. Check the compatibility of your provider constraint with those versions before the first deployment.

A configuration that is meant to run in Infra Manager therefore looks like this:

Source: Google Cloud — Terraform and Infrastructure Manager

Before the first deployment, enable the config.googleapis.com API and create the service account the deployment runs as. Grant it roles/config.agent in the project that runs Infra Manager, plus the roles the resources need (and, for the resources being deleted by an update, the permissions to delete them). People who create deployments need roles/config.admin and roles/iam.serviceAccountUser on that service account. When the service account lives in another project than the deployment, extra grants are needed: the organization policy constraint iam.disableCrossProjectServiceAccountUsage must not be enforced on the service account’s project, and the Infra Manager service agent needs roles/iam.serviceAccountUser there.

Source: Google Cloud — Deploy infrastructure using Infrastructure Manager and Preview a deployment

Use --gcs-source gs://BUCKET/OBJECT for a zipped configuration in Cloud Storage (versioned buckets let you pin a generation), or --git-source-repo, --git-source-directory and --git-source-ref for Git. A private repository must first be connected to Cloud Build or Developer Connect. --quota-validation can be ENABLED (report) or ENFORCED (fail when quota is insufficient); leaving it out disables the check, and it only covers a limited set of resources.

A deployment is deleted with gcloud infra-manager deployments delete, which destroys the resources; the option --delete-policy=abandon removes the deployment but leaves the resources in place, which is the safe way to hand them to a different tool.

The provider has a resource for the deployment, google_config_deployment, so even the Infrastructure Manager layer can be code. Its required arguments are name, location, service_account and a terraform_blueprint block with either a gcs_source or a git_source (repo, directory, ref) and any number of input_values blocks. Optional arguments include tf_version_constraint, artifacts_gcs_bucket, worker_pool, quota_validation, import_existing_resources and force_destroy. The documentation describes the Git source as a public repository.

Source: Terraform Registry — google_config_deployment

Infra Manager removes the need to host a runner, to store state yourself and to hand credentials to a CI system: the deployment runs as a service account inside Google Cloud, previews and revisions are first-class, and audit logs record who changed what. The price is a Terraform version of at most 1.5.7 on the documented list, state that you reach only through the lock, export and import commands, and none of the language and CLI features added since. A pipeline that you operate (see CI/CD and Automation), or HCP Terraform (HCP Terraform and Terraform Enterprise), gives you the current language and CLI, at the cost of running more yourself. Many teams use Infra Manager for a few well-bounded foundations, for example a landing-zone repository, and a normal pipeline for application stacks. Config Connector and Deployment Manager are covered in the Google Cloud section. Deployment Manager support was discontinued on 2026-04-01, the maximum extension of support for migration blockers ends on 2027-03-31, and the service is turned down after 2027-06-30; Infra Manager is the migration target.

Following the guidance, split the Bookshelf into layers that change at different speeds and that have different owners. Each directory is a root module with its own state object in the same bucket.

Source: Google Cloud — Best practices for root modules

One directory per environment with several layers inside it is the compromise most teams settle on: the network and data layers are separate states with separate prefixes (for example bookshelf/prod/network), so a mistake in an application change cannot touch the database, and they share modules with the other environments. How to wire several states together, and when Terraform Stacks or HCP Terraform are better, is covered in Workspaces, Environments and Project Structure.

The diagram shows the order in which layers are applied (and, reversed, destroyed). The bootstrap layer creates the state bucket and the identities, then each layer reads what it needs from the previous ones through remote state outputs.

The first resource most people create on Google Cloud is a Cloud Storage bucket, and it is the right place to learn the workflow. The covers bucket holds book cover images, so it is private, versioned and labelled.

Source: Terraform Registry — google_storage_bucket

Bucket names are global across all of Google Cloud, which is why the name embeds the project ID, and they cannot be reused for a while after deletion. force_destroy defaults to false, in which case destroying a bucket that still contains objects fails; the expression above relaxes it everywhere except production. The uploads/ prefix rule only makes sense if the application writes there, so replace it with your own layout.

The workflow around the resource is the standard one, with a saved plan so that what was reviewed is what is applied:

Source: Terraform Docs — terraform plan

Introductory material often creates several resources with count and passes values with -var. -var on the command line is fine for a demonstration, but Google’s guidance prefers terraform.tfvars for root modules because command-line values are easy to forget. count identifies instances by position, so removing the first element shifts every address and plans a destroy-and-create for the others; for_each over a map or set keys them by name. Both are described in count, for_each and depends_on.

A custom-mode VPC with explicit subnets is the only sensible starting point: auto_create_subnetworks creates a subnet in every region from 10.128.0.0/9 when set to true, which collides with anything you later connect. The example drives subnets and firewall rules from locals, uses a dynamic block for the repeated allow blocks, and exposes the results with a for expression.

Source: Terraform Registry — google_compute_network, google_compute_subnetwork and google_compute_firewall

Google Cloud firewall rules are stateful, apply to a whole VPC network, and are matched by target tag or target service account, never by subnet. Every VPC has two implied rules, allow all egress and deny all ingress, which is why the configuration only lists exceptions. Tags are free text and anyone who can edit an instance can add one, so for sensitive workloads use target_service_accounts instead of target_tags. If your organization uses network firewall policies, google_compute_network_firewall_policy and its rule resources are the modern alternative; the network_firewall_policy_enforcement_order argument of the network decides how policies and classic rules interleave. The security model is in VPC networking. Subnet flow logs and firewall logs cost money in proportion to traffic, so use the sampling and aggregation arguments deliberately.

Cloud SQL private IP and Cloud Run’s Direct VPC egress both use this network. For Cloud SQL, a private services access connection reserves an internal range and peers the VPC with Google’s service-producer network:

Source: Terraform Registry — google_service_networking_connection

The Cloud SQL resource page stresses that the instance does not interpolate anything from the connection, so the instance must declare an explicit depends_on for it. The connection also has a deletion_policy; see the clean-up section for why it matters.

Wang’s chapter builds a single instance, then several through a module, then a multi-zone fleet driven by a map in terraform.tfvars. The same progression is shown here in one resource, which is what a module would wrap. The variable is a map(object(...)) with optional attributes and defaults, so that adding a VM is a data change.

Source: Terraform Registry — google_compute_instance

Source: Terraform Docs — Input variables

The debian-cloud/debian-13 value is an image family: Google’s operating system details page lists debian-13 as a generally available image family, while Debian 10 and 11 are marked end of service, so snippets that use debian-10 or debian-11 should be replaced. The file name matters: terraform.tfvars, terraform.tfvars.json and files ending in .auto.tfvars are loaded automatically; a file called tf.tfvars is not, and needs -var-file. Never attach the default Compute Engine service account (it is highly privileged by default) and never leave VMs with external IPs unless something requires it; reach them through IAP, as the firewall rule above allows. For a fleet that must scale or heal itself, a managed instance group with an instance template is the proper building block; google_compute_instance is for pets and small fixed fleets. See Compute Engine.

Container images live in Artifact Registry, because Container Registry (gcr.io) was shut down on 2025-03-18 according to the Google Cloud section of this site. The baseline in Infrastructure as Code on Google Cloud creates the repository; the version below adds cleanup policies, which delete untagged images and keep recent versions so that the repository does not grow without bound. If you applied the baseline first, import its repository into this layer instead of creating a second one, as described in Import and Query.

Source: Terraform Registry — google_artifact_registry_repository

With cleanup_policy_dry_run set to true the policies are evaluated and reported but nothing is deleted; turn it off after reading the audit logs. In 7.0.0 the defaults of the public_repository fields of remote repositories were removed, which matters only if you proxy upstream registries.

The database is the part of the Bookshelf that must never be destroyed by accident, so it receives every protective argument the resource has. The example uses PostgreSQL 18, the default major in Cloud SQL according to the database version policy page checked for this page, regional high availability, point-in-time recovery, private IP only, and TLS required.

Source: Terraform Registry — google_sql_database_instance and Cloud SQL — Database version policies

Several details of this resource explain most of the surprises people meet:

The google_sql_ssl_cert resource still exists for client certificates, but the provider documents that all its arguments, including the private key, are stored in plain text in state. Prefer ssl_mode = ENCRYPTED_ONLY together with the Cloud SQL Auth Proxy or the language connectors, which verify the server through IAM and do not need client certificates; see Cloud SQL.

A read replica is another instance that names the primary in master_instance_name; the provider documents that replication requires existing backups (and binary logging for MySQL) on the primary. Promoting a replica to a standalone instance is done by setting instance_type to CLOUD_SQL_INSTANCE and removing the master reference.

Source: Terraform Registry — google_sql_database_instance

A google_sql_user with a literal password argument writes the password into state, which is exactly the anti-pattern the next major section describes. Since Terraform 1.11 the resource accepts a write-only password, password_wo, which is sent to the API but never stored, together with password_wo_version, which you increment to rotate. Provider 7.0.0 made the two arguments mandatory as a pair. The value itself can come from an ephemeral read of Secret Manager, so that it never reaches state or the plan either:

Source: Terraform Registry — google_sql_user, google_secret_manager_secret_version (ephemeral) and Using write-only arguments

Ephemeral resources are explained in Sensitive Data, Ephemeral Resources and Write-only Arguments. Because the ephemeral read happens at plan time, the very first apply of a fresh environment needs two steps: create the secret container (target the google_secret_manager_secret resource, or apply a separate layer), add a version with gcloud, then apply the rest. The secret then lives in Secret Manager, its version history is controlled by IAM, and rotation is a new version plus an increment of password_wo_version.

google_cloud_run_service, the Knative-style resource that older material uses, has been superseded by google_cloud_run_v2_service, which maps onto the Cloud Run Admin API v2. The v2 service configures revision settings under template and service-level settings (ingress, traffic, scaling) at the top. Since provider 6.0.0 it has deletion_protection, which defaults to true; the baseline page sets it to false for a throwaway sample, and a real production service should leave it on and flip it only to destroy.

Source: Terraform Registry — google_cloud_run_v2_service, google_cloud_run_v2_service_iam and Cloud Run — Connecting to a VPC network

Points worth knowing about this resource:

Wang’s pipeline chains Cloud Storage, Pub/Sub, a Cloud Function, Cloud Run and BigQuery. The Bookshelf version has the same shape and current parts: an uploaded cover (object finalized in the covers bucket) triggers a function that generates thumbnails and publishes a JSON event to a Pub/Sub topic; a BigQuery subscription writes the events straight into a table without any code in between; catalog-api (above) serves the results.

Cloud Functions 2nd generation was renamed Cloud Run functions in August 2024 (release note of 2024-08-21), but the provider resource is still google_cloudfunctions2_function, and the legacy google_cloudfunctions_function is the 1st generation product. The 2nd generation resource is built on Cloud Run and Eventarc: it has build_config (runtime, entry point, source), service_config (memory, CPU, concurrency, scaling, VPC settings, secrets, ingress, service account) and an optional event_trigger. From provider 7.0.0 event_trigger.event_type is required, and service_config.service is output only. Runtimes are listed on the Cloud Run functions runtime support page (it showed python313 and nodejs22 as supported while older Node.js runtimes such as nodejs20 are past their support dates), so check it before choosing one.

Source: Terraform Registry — google_cloudfunctions2_function and Cloud Run functions — Runtime support

The event, the IAM roles and the ordering follow the provider’s own Cloud Storage example. Some more points:

The BigQuery half has more to say about identity than about code. A BigQuery subscription is a Pub/Sub subscription with a bigquery_config block: Pub/Sub writes each message into the table without a consumer, either to a single data column, or, with use_table_schema, into the columns of the table, in which case messages must be JSON. Which identity writes is selected with service_account_email; the documented default is the Pub/Sub service agent, but a dedicated account is easier to audit and to grant narrowly.

Source: Terraform Registry — google_pubsub_subscription, google_bigquery_table and google_bigquery_dataset

deletion_protection on google_bigquery_table is enabled unless it is set, so destroying a table needs two steps: set it to false, apply, then destroy. drop_unknown_fields makes Pub/Sub discard message fields that are not columns of the table; without it, messages with extra fields stay in the backlog. A topic, subscription or table that changes shape should be treated as a migration, not as an in-place edit.

Wang creates service accounts and downloads JSON keys. The right default today is: create service accounts with google_service_account, grant roles with the non-authoritative google_project_iam_member, and never create keys. A google_service_account_key resource stores the private key in state and produces a credential that does not expire; every use case that seems to need one has a keyless alternative:

Source: Google Cloud — Best practices for security and Terraform Registry — google_service_account_key

Granting the Owner, Editor or Viewer basic roles to a service account is explicitly discouraged in production by Google’s authentication documentation; use predefined or custom roles scoped to what the account does. The IAM resources are covered in the next major section.

Wang provisions a GKE cluster with node pools, add-ons, network policy and the Kubernetes provider to create a Service, an Ingress and RBAC objects. The Kubernetes half moves to Docker, Kubernetes and Helm Providers, including the two-phase apply problem when a provider is configured from a cluster that does not exist yet, and the guidance to hand application delivery to Helm or GitOps (see the Kubernetes section). What belongs here is the cluster itself:

Source: Terraform Registry — google_container_cluster

An Autopilot cluster has no node pools to manage and applies hardened defaults; use Standard clusters only when you need node-level control, and then create node pools as separate google_container_node_pool resources with remove_default_node_pool. The range 203.0.113.0/24 is a documentation address; the point is that authorized networks should list real administrator ranges, never 0.0.0.0/0, which defeats the control. deletion_protection is a google_container_cluster argument too. The provider’s own guide on GKE (using_gke_with_terraform) and the section GKE clusters cover node pools, upgrades and networking in depth.

The usual ways a Terraform project leaks a secret on Google Cloud, in order of how often they happen, are:

Source: Terraform Docs — Manage sensitive data and Google Cloud — Best practices for security

A secret has two parts in Secret Manager and in Terraform. The secret (google_secret_manager_secret) is a named container with replication, labels, rotation and expiry settings. A version (google_secret_manager_secret_version) holds the payload. Terraform can manage both, but the payload is the part that must stay out of state. The service itself is covered in Secret Manager and KMS.

The arguments of the secret that matter most:

Source: Terraform Registry — google_secret_manager_secret

For the payload there are two options. secret_data is sensitive in plan output but is stored in state. secret_data_wo is write-only: it is sent to the API and never stored, so a rotation is expressed by changing secret_data_wo_version, which Terraform does store and compare. The two are mutually exclusive. Provider 8.0.0 changed the contract: secret_data_wo_version became a string (existing state converts on the first apply), and it is required whenever secret_data_wo is set, with the old implicit default of 0 removed. If your configuration still has an integer there, quote it before upgrading.

Source: Terraform Registry — google_secret_manager_secret_version

For rotation notifications to be delivered, the Secret Manager service agent needs roles/pubsub.publisher on the topic, as the provider documents; that agent can be created with google_project_service_identity (a beta resource, as described below) and granted with google_pubsub_topic_iam_member.

Run it with TF_VAR_reviews_api_key in the environment (it is never printed because the variable is both sensitive and ephemeral), and increment secret_data_wo_version (a string) when you want a new version. deletion_policy set to DISABLE makes terraform destroy disable the version instead of destroying it, and ABANDON leaves it alone; the default destroys.

Two lifecycle points deserve care when secret_data (not the write-only argument) is used. Changing the data replaces the version resource, so a plain replacement destroys the old version before the new one exists unless you ask for the other order with lifecycle { create_before_destroy = true }; with that setting consumers that read latest never see a moment with no enabled version. And a secret that has a ttl or expire_time will disappear on schedule even though Terraform still lists it, so treat the expiry as part of the contract, not as a clean-up.

Reading secrets back into Terraform has the same two options. The google_secret_manager_secret_version data source puts the payload into state; the ephemeral resource with the same name does not (see the Cloud SQL user earlier). The only legitimate reason to use the data source is a value that is not secret.

Google encrypts data at rest by default. Customer-managed encryption keys (CMEK) in Cloud KMS give you control of the key’s rotation, disablement and audit trail, and satisfy policies that require it. They are configured per resource: Cloud Storage buckets (encryption.default_kms_key_name), Cloud SQL (encryption_key_name), Pub/Sub topics (kms_key_name), BigQuery datasets (default_encryption_configuration), Secret Manager (customer_managed_encryption with kms_key_name, inside replication) and the state backend (kms_encryption_key).

Three properties of Cloud KMS shape the Terraform code. A key ring and a key cannot be deleted from a project; destroying the Terraform resource only removes it from state, and for a key it also deletes the key versions, after which anything encrypted with it is unrecoverable (versions pass through a scheduled-destruction period, 30 days by default, configurable with destroy_scheduled_duration when the key is created). The rotation_period must be longer than a day. And each Google service that uses your key does so through its own service agent, which must be granted roles/cloudkms.cryptoKeyEncrypterDecrypter on the key, before the dependent resource is created.

Source: Terraform Registry — google_kms_crypto_key, google_storage_bucket and google_kms_crypto_key_iam

The key and the bucket must be in compatible locations. For services whose service agent is not exposed by a data source, the google_project_service_identity resource creates it. At the time of writing that resource is documented as beta, so it needs provider = google-beta, and once created it cannot be updated or destroyed (those actions do nothing). This is the typical reason to keep a google-beta provider block in an otherwise GA configuration:

Source: Terraform Registry — google_project_service_identity

Encryption in transit is configured separately and was shown earlier: ssl_mode = ENCRYPTED_ONLY on Cloud SQL, HTTPS-only Cloud Run endpoints, private Google access on subnets, and storage_custom_endpoint for the state backend.

Google Cloud IAM resources in the provider come in three flavours for every kind of resource, and mixing them is the most common source of surprising plans:

Source: Terraform Registry — google_project_iam

Together with the earlier advice, the practical rules are: grant roles with the member form; scope each grant as narrowly as possible (a role on a secret, a bucket, a service or a repository beats a role on the project); use predefined roles, and a custom role only when no predefined role fits; and never grant the basic Owner, Editor or Viewer roles to workloads. The provider’s member attribute on google_service_account produces the right serviceAccount: string.

A custom role and a conditional grant look like this. IAM conditions use Common Expression Language and apply to the binding they are attached to; the example grants a contractor temporary read access to logs.

Source: Terraform Registry — google_project_iam_custom_role and google_project_iam

The role_id of a custom role is camel case and cannot contain a hyphen. Custom roles are for a project or an organization and need stage to say whether they are in alpha, beta or general availability. The permissions list must be checked against the permissions the services actually need; use the IAM Recommender and the audit logs rather than guesswork.

The external data source, which the book uses to compute IAM values with scripts, is an escape hatch with a clear protocol: a program reads a JSON object of strings from standard input and prints a JSON object of strings on standard output, and runs on every refresh. Its documentation warns that it hurts portability and that it is not recommended in Terraform Enterprise. Almost everything IAM needs is available through provider resources and data sources (for example google_iam_policy, google_project, google_service_account), so reach for external last.

Source: Terraform Registry — external data source

The state bucket is the most sensitive object of the whole configuration. Most of the work is in the bootstrap section; the checklist below connects the controls to Google’s guidance.

Source: Google Cloud — Best practices for security

Google Cloud writes Admin Activity audit logs for administrative operations without configuration. Data Access audit logs, which record reads of data and of configuration, are disabled by default for all services except some BigQuery ones, are billed as log volume, and must be turned on per service, for example for Cloud Storage and Secret Manager. In Terraform that is google_project_iam_audit_config; a sink (google_logging_project_sink) routes matching log entries to a destination, and an alert policy reacts to metrics.

Source: Terraform Registry — google_logging_project_sink, google_project_iam (audit config) and google_monitoring_alert_policy

Three notes. First, project_iam_audit_config is authoritative for a given service: it replaces the existing audit configuration of that service, so declare it in one place only. Second, the sink’s writer_identity is only known after creation, which is why the bucket grant is a separate resource; the sink can start before the grant exists and drop entries until it does, so keep the dependency. Third, the metric type and resource type in the filter are those of Cloud SQL; check them against the Metrics Explorer for the service you alert on. The monitoring section of the Google Cloud pages, Monitoring and observability, covers metrics, log-based metrics and uptime checks in depth. Security Health Analytics, mentioned in Google’s best practices as a post-apply audit, and gcloud beta terraform vet as a pre-apply check, are the Google-native counterparts of the scanners in Code Quality and Security Scanning.

A Terraform configuration is a recovery plan for infrastructure, not for data. Plan for four kinds of loss:

Source: Terraform Registry — google_compute_resource_policy and google_storage_bucket

DNS plays a part in failover: users reach the Bookshelf through a name, so keep the TTL of the records that point at it low enough that a switch to another region takes effect quickly, and manage the zone and record sets in their own layer (google_dns_managed_zone, google_dns_record_set) so that rebuilding an application layer never touches them. Cloud DNS is described in Cloud DNS and certificates.