Terraform google Provider実務ガイド: GCPでのよくある設定とAssociate対策

TerraformでGCPを扱う際、最初につまずきやすいのがgoogle Providerの基本設定です。認証の取り回し、project/region/zoneの優先順位、モジュール間のプロバイダ受け渡し、State保護、API有効化、そして請求プロジェクトの指定など、どれも実務と試験の双方で問われやすい論点です。

ここではTerraform Associate相当の範囲で、安定した公式挙動に基づく“よくある設定”を、最短で安全に整えるための実務視点でまとめます。

認証の基本: ADC/サービスアカウント鍵/インパーソネーションの使い分け

最初に決めるべきは認証方式です。Terraformのgoogle ProviderはApplication Default Credentials(ADC)を優先します。ローカル開発ではgcloud auth application-default login、CI/CDではサービスアカウントの短命トークンやインパーソネーション(impersonate_service_account)が堅実です。

長期保存のJSON鍵は管理コストと漏えいリスクが高いため、可能なら避けます。既存の運用で鍵ファイルが必要な場合でも、今後はインパーソネーションやID連携(Workload Identity Federationなど)への移行計画を持つのが安全です。

• 優先順イメージ: 環境変数や明示設定 > ADCの順で解決される
• GOOGLE_APPLICATION_CREDENTIALS はローカルの簡易手段。CIでは短命資格情報を優先
• impersonate_service_account は鍵不要で権限を最小化しやすい
• access_token の直指定は最小限に。更新と失効タイミングの管理が難しい

TerraformによるGCP認証フロー(概念図)

最小構成とインパーソネーション例

# ベース: 環境変数やADCで認証を解決する前提
provider "google" {
  project = var.project
  region  = var.region
  zone    = var.zone
}

# インパーソネーションを使う例（CI/CDで推奨されやすい）
provider "google" {
  project                    = var.project
  region                     = var.region
  impersonate_service_account = var.impersonated_sa_email
  # 必要に応じ request_timeout 等の基本チューニングも可能
  # request_timeout = "60s"
}

variable "project" {}
variable "region"  { default = "us-central1" }
variable "zone"    { default = "us-central1-a" }
variable "impersonated_sa_email" { default = null }

project/region/zone の優先順位と設計

google Providerで project/region/zone を指定しておくと、多くのリソースはそのデフォルトを継承します。ただし、個々のリソースで location/region/zone を明示できるものは、リソース側の指定が優先されます。モジュール境界をまたぐ場合は、入力変数として受け渡し、意図しないリージョン混在を避けます。

Computeのゾーン資源(例: google_compute_instance)とリージョン資源(例: google_compute_subnetwork)は必要な粒度が異なります。location を持つデータ分析系(BQ/GCS)はマルチリージョンを選ぶこともありますが、プロバイダの region と一致させる必要はありません。

• 優先順位の基本: リソース内の明示設定 > providerのデフォルト
• モジュールでの暗黙依存を避けるため、project/region/zoneは明示的に引き回す
• 混在を検知しやすいよう命名規則やtfvarsを環境ごとに分離

リソースごとのlocation/region/zone上書き例

# provider側のデフォルト
provider "google" {
  project = var.project
  region  = "us-central1"
  zone    = "us-central1-a"
}

# ゾーン資源（デフォルトを継承）
resource "google_compute_instance" "vm" {
  name         = "app-1"
  machine_type = "e2-medium"
  boot_disk { initialize_params { image = "debian-cloud/debian-12" } }
  network_interface { network = "default" }
}

# リージョン資源（providerのregionを継承）
resource "google_compute_address" "addr" {
  name   = "app-addr"
}

# 明示的に別リージョンへ配置
resource "google_compute_subnetwork" "subnet_eu" {
  name          = "app-subnet-eu"
  ip_cidr_range = "10.10.0.0/24"
  region        = "europe-west1"  # providerのregionを上書き
  network       = "default"
}

aliasでマルチプロジェクトを安全に扱う

監査用・共有基盤用など、複数のGCPプロジェクトを横断する構成では、providerのaliasを使います。各aliasに明確なprojectと認証(必要ならインパーソネーション)を結び、モジュールにはprovidersマップで対応するエイリアスを渡します。

モジュール内部で複数のプロバイダを使う場合、providerメタ引数でどのエイリアスを使うかを明示します。これにより、誤ったプロジェクトへ誤配置する事故を避けられます。

• alias名は役割ベースで分かりやすく: audit, shared, prod など
• モジュール境界では providers マップで必ず受け渡す
• 同一リソースタイプでも provider = google.audit のように明示可能

alias定義とモジュールへの受け渡し

# 2つのプロジェクトを操作する例
provider "google" {
  alias   = "app"
  project = var.app_project
  region  = var.region
}

provider "google" {
  alias   = "audit"
  project = var.audit_project
  region  = var.region
  impersonate_service_account = var.audit_impersonated_sa
}

module "network" {
  source = "./modules/network"
  # モジュール内で `provider = google.audit` を使うリソースがある想定
  providers = {
    google        = google.app
    google.audit  = google.audit
  }
  project_app   = var.app_project
  project_audit = var.audit_project
}

variable "app_project" {}
variable "audit_project" {}
variable "region" { default = "us-central1" }
variable "audit_impersonated_sa" { default = null }

GCSバックエンドでのState保護と基本設定

Terraformの状態はチームで共有し、同時実行を抑止する必要があります。GCSバックエンドはバケットの世代管理(オブジェクトバージョニング)と原子的な書き込みにより、基本的な整合性を担保します。DynamoDBのような外部ロックは不要ですが、CIのジョブ並列度は制御してください。

最低限、GCSバケットにバージョニングを有効化し、適切なIAM(読み取り:閲覧者、書き込み:管理者)を設定します。環境ごとにprefixを分けると復元や切り戻しが容易になります。

• バケットのバージョニング有効化は実務の必須設定
• 環境/ワークスペースごとにprefixを分離
• サービスアカウントの最小権限: storage.objects.get/compose/update 程度に限定

GCSバックエンドの基本例

terraform {
  backend "gcs" {
    bucket = "my-tfstate-bucket"
    prefix = "envs/prod"
  }
  required_version = ">= 1.5.0"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 5.0"
    }
  }
}

# バケット側は別途作成し、バージョニングを有効化しておく

API有効化と依存関係、リトライ/タイムアウトの基本

GCPでは多くのサービスでAPI有効化が必要です。google_project_serviceで先に有効化し、主要リソースがそれに依存するよう明示します。初回有効化直後は内部反映に時間がかかることがあり、plan/applyのリトライやtimeoutの調整が役立ちます。

Providerレベルのrequest_timeoutはAPI呼び出し全体の上限を広げるのに有用です。失敗時の再実行に備え、idempotentな定義と適切なdepends_onでの順序制御を心がけます。

• google_project_serviceでAPIを明示的に有効化してから依存リソースを作成
• 初回有効化の反映遅延を見越してrequest_timeoutを調整
• for_eachで複数APIを一括有効化し、欠落を防ぐ

API有効化と依存の例

locals {
  required_apis = [
    "compute.googleapis.com",
    "iam.googleapis.com",
    "cloudresourcemanager.googleapis.com"
  ]
}

resource "google_project_service" "enable" {
  for_each           = toset(local.required_apis)
  project            = var.project
  service            = each.key
  disable_on_destroy = false
}

resource "google_service_account" "deployer" {
  project      = var.project
  account_id   = "deployer"
  display_name = "Deployer SA"
  depends_on   = [google_project_service.enable]
}

provider "google" {
  project         = var.project
  request_timeout = "60s"
}

billing_project と user_project_override の使い所

一部のAPIでは、クォータや課金を別プロジェクトで計上したいケースがあります。google Providerのbilling_projectに課金先プロジェクトを指定し、必要に応じてuser_project_overrideをtrueにすると、課金やクォータの消費を指定プロジェクト側に寄せることができます。

これらは全APIで必要ではありません。要件がない限りは未設定で問題ありませんが、監査/共有プロジェクトに課金を集中させる設計では有効です。

• billing_project は“請求/クォータの帰属”に関係
• user_project_override はユーザープロジェクト課金を強制するオプション
• 不要な場面では指定しない(デフォルト安全)

billing_project と user_project_override の指定例

provider "google" {
  project              = var.project
  region               = var.region
  billing_project      = var.billing_project
  user_project_override = true
}

variable "project" {}
variable "region" { default = "us-central1" }
variable "billing_project" { default = null }

問題で確認

よくある質問