☁️ Google Cloud Service Account Terraform Module

Creates and manages a single Google Cloud IAM service account (google_service_account) — never a key. Targets hashicorp/google ~> 7.0, Terraform >= 1.12.0.

• 🔑 Creates one google_service_account — the IAM identity GCP workloads and CI/CD pipelines assume to call Google Cloud APIs.
• 🚫 Never creates a google_service_account_key — no downloadable key material is generated by this module, ever.
• 🏷️ Exposes the identity in every consumable form (id, email, name, unique_id, member) so sibling IAM-binding and compute modules can wire it in without re-deriving any string.
• 🧱 Standalone by design — a service account has no natural for_each-managed child collection, so this module stays a single keystone resource with no composite shape.

💡 Why it matters: a service account is the identity every other workload-facing module in this library eventually grants access to or runs as. Getting its creation right — and keeping key material out of the picture entirely — is a foundational control, not an implementation detail.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

graph LR
 SA["terraform-google-service-account"]:::thisModule
 IAMB["terraform-google-project-iam-bindings"]:::keystoneSibling
 GKE["terraform-google-gke-cluster"]:::sibling
 CI["terraform-google-compute-instance"]:::sibling
 IT["terraform-google-instance-template"]:::sibling
 CR["terraform-google-cloud-run-service"]:::sibling
 PS["terraform-google-project-services"]:::external

 PS -- "enables iam.googleapis.com" --> SA
 SA -- "email consumed as member" --> IAMB
 SA -- "email / id consumed by service_account field (future)" --> GKE
 SA -- "email / id consumed by service_account field (future)" --> CI
 SA -- "email / id consumed by service_account field (future)" --> IT
 SA -- "email consumed by service_account.email (future)" --> CR

 classDef thisModule fill:#4285F4,color:#ffffff,stroke:#174EA6,stroke-width:1px;
 classDef keystoneSibling fill:#174EA6,color:#ffffff,stroke:#174EA6,stroke-width:1px;
 classDef sibling fill:#E8EAED,color:#202124,stroke:#9AA0A6,stroke-width:1px;
 classDef external fill:#E8EAED,color:#202124,stroke:#9AA0A6,stroke-width:1px,stroke-dasharray: 3 3;

terraform-google-project-services (external, dashed) must have already enabled iam.googleapis.com before this module applies. terraform-google-project-iam-bindings is this module's most direct consumer today, taking the member output straight into its own for_each binding map. The compute/GKE/Cloud Run siblings are documented future consumers of email/id (their service_account fields) — this library does not yet ship those modules wired to this one, but the identity contract is stable today.

graph LR
 subgraph Inputs
 A["var.account_id"]
 B["var.display_name"]
 C["var.description"]
 D["var.disabled"]
 E["var.create_ignore_already_exists"]
 F["var.timeouts"]
 end

 R["google_service_account.this"]:::thisModule

 A --> R
 B --> R
 C --> R
 D --> R
 E --> R
 F --> R

 R --> O1["output: id"]
 R --> O2["output: email"]
 R --> O3["output: name"]
 R --> O4["output: unique_id"]
 R --> O5["output: member"]

 classDef thisModule fill:#4285F4,color:#ffffff,stroke:#174EA6,stroke-width:1px;

Resource inventory: exactly one resource, google_service_account.this. No nested/repeating configuration blocks (the live schema has none for this resource) and no child resources — no for_each, no composite shape.

Schema notes that bite (verified against hashicorp/google v7.39.0 via terraform-registry):

• account_id is force-new — changing it destroys and recreates the service account. There is no in-place rename.
• account_id must be 6–30 characters, start with a lowercase letter, and match [a-z]([-a-z0-9]*[a-z0-9]) (RFC1035-style) — a hard GCP API constraint, enforced here at plan time via validation {}.
• disabled has no effect during creation — GCP always creates the service account enabled; disabling it requires a subsequent apply with disabled = true.
• description must be ≤ 256 UTF-8 bytes; this module's validation {} checks character count as a plan-time proxy (Terraform has no native byte-length function) — non-ASCII text can hit the real byte limit before 256 characters.
• This resource has no self_link and no labels argument — both are common on most GCP resources but absent from the IAM Service Account API. See Architecture Notes.
• timeouts supports only create (default 5 minutes) — no update/delete timeout exists in the schema.

• roles/iam.serviceAccountAdmin on the target project — create, update, and delete service accounts. No broader project-level role is required by this module alone.

• iam.googleapis.com enabled on the target project (via terraform-google-project-services, applied before this module).

terraform-google-service-account/
├── providers.tf # required_providers (hashicorp/google ~> 7.0) + required_version — no provider {} block
├── variables.tf # account_id, display_name, description, disabled, create_ignore_already_exists, timeouts
├── main.tf # google_service_account.this — the sole resource
├── outputs.tf # id, email, name, unique_id, member
├── README.md # this file
├── SCOPE.md # lightweight cross-module contract
└── examples/ # runnable example matching the Quick Start below

module "runtime_service_account" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id   = "app-runtime"
  display_name = "Application runtime identity"
}

The caller's root module configures the google provider (project, region/zone, and authentication via ADC, Workload Identity Federation, or a service account key supplied out-of-band) — this module accepts none of those as variables.

Consumes

Emits

This resource has no self_link — none is emitted.

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id = "app-runtime"
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id   = "billing-export"
  display_name = "Billing Export Job"
  description  = "Runs the nightly BigQuery billing export; owned by the FinOps team."
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id = "legacy-batch-job"
  disabled   = true
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id                   = "shared-ci-runner"
  create_ignore_already_exists = true
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id = "slow-org-policy-project"

  timeouts = {
    create = "10m"
  }
}

module "gke_workload_sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id   = "gke-orders-api"
  display_name = "GKE Orders API workload identity"
}

# terraform-google-gke-cluster (or a Kubernetes-side IAM binding) would consume:
# module.gke_workload_sa.email
# as the Workload Identity-bound service account — no key material involved.

module "cloud_run_sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id   = "cloud-run-api"
  display_name = "Cloud Run API runtime identity"
}

# terraform-google-cloud-run-service would consume module.cloud_run_sa.email as its
# google_cloud_run_v2_service.template.service_account value.

module "cicd_sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id   = "github-actions-deploy"
  display_name = "GitHub Actions deployment identity"
  description  = "Impersonated via Workload Identity Federation; no key material issued."
}

locals {
  service_accounts = {
    "orders-api"    = "Orders API runtime identity"
    "inventory-api" = "Inventory API runtime identity"
  }
}

module "workload_sas" {
  source   = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"
  for_each = local.service_accounts

  account_id   = each.key
  display_name = each.value
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id = "sa-abc" # 6 characters — the minimum GCP allows
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id = "app-runtime-prod-us-east1-01" # 28 characters — within the 30-char limit
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id  = "audit-log-exporter"
  description = "Exports audit logs from Cloud Logging to a long-term retention bucket for compliance review; owned by the Security Engineering team; rotated per the records retention schedule."
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id = "bucket-reader"
}

resource "google_storage_bucket_iam_member" "reader" {
  bucket = "my-existing-bucket"
  role   = "roles/storage.objectViewer"
  member = module.sa.member
}

module "sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id   = "wif-deploy-target"
  display_name = "WIF impersonation target for deploy pipeline"
}

# A separate WIF pool/provider module (not in this library's current catalog) would bind:
# principalSet://iam.googleapis.com/<pool>/attribute.repository/<org>/<repo>
# to module.sa.email via a google_service_account_iam_member with
# roles/iam.workloadIdentityUser — configured outside this module's scope.

module "project_services" {
  source = "git::https://github.com/microsoftexpert/terraform-google-project-services.git?ref=v1.0.0"

  # Enables iam.googleapis.com (and any other APIs the composition needs) —
  # applied before every other module in this composition.
}

module "orders_api_sa" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id   = "orders-api"
  display_name = "Orders API runtime identity"
  description  = "Runtime identity for the Orders API Cloud Run service."

  depends_on = [module.project_services]
}

module "orders_api_iam" {
  source = "git::https://github.com/microsoftexpert/terraform-google-project-iam-bindings.git?ref=v1.0.0"

  bindings = {
    "orders-api-pubsub-publisher" = {
      role   = "roles/pubsub.publisher"
      member = "serviceAccount:${module.orders_api_sa.email}"
    }
    "orders-api-secret-accessor" = {
      role   = "roles/secretmanager.secretAccessor"
      member = "serviceAccount:${module.orders_api_sa.email}"
    }
  }
}

variable "account_id" {
  type = string
  # 6-30 chars, ^[a-z][-a-z0-9]{4,28}[a-z0-9]$ enforced via validation {}
}

variable "display_name" {
  type    = string
  default = null
}

variable "description" {
  type    = string
  default = null
  # <= 256 characters enforced via validation {} (proxy for GCP's 256 UTF-8 byte limit)
}

variable "disabled" {
  type    = bool
  default = false
}

variable "create_ignore_already_exists" {
  type    = bool
  default = false
}

variable "timeouts" {
  type = object({
    create = optional(string)
  })
  default = null
}

ℹ️ No self_link row: this resource does not export one. Unlike most GCP resources covered by this library, the IAM Service Account API has no self_link concept — id is the only Terraform-internal reference form.

None of these outputs are secret-bearing; no sensitive = true is applied to any of them.

• account_id is force-new. Changing it destroys and recreates the service account. Per the live provider docs, recreating a service account does not restore any IAM roles it previously held — those must be reapplied (typically automatic if the same for_each key still grants them in terraform-google-project-iam-bindings, but any binding managed outside Terraform is lost for good).
• Eventual consistency on creation. GCP's IAM Service Account API is eventually consistent. Granting IAM roles to, or otherwise referencing, a service account created in the same apply can transiently fail even when the Terraform graph correctly orders creation before the dependent resource. This is an operational characteristic of the API, not a defect in this module or its callers.
• No labels variable — deliberate schema-driven omission. The live google_service_account schema (verified against the live provider schema, hashicorp/google v7.39.0) has no labels argument. GCP's IAM Service Account API simply does not support resource labels, unlike the large majority of GCP resources this library targets. Per this module suite's own post-module checklist, a module documents this as an exception rather than fabricating a variable with no effect on the underlying resource — adding a decorative labels input here would violate the house rule that main.tf is a total, honest renderer of what the resource actually accepts.
• No self_link output — same reasoning. The resource simply does not export one.
• timeouts models only create. The schema has no update/delete timeout for this resource; the variable intentionally does not offer fields the provider would silently ignore.

cd terraform-google-service-account
terraform init -backend=false
terraform validate
terraform fmt -check

Pin the module source to ?ref=v1.0.0 — never a branch. This library is plan-only from an authoring session; a human applies from CI with valid Workload Identity Federation or ADC credentials.

terraform validate confirms internal type and reference consistency (e.g. account_id's validation {} block, correct resource/output wiring). terraform fmt -check confirms canonical formatting. Neither can catch GCP API-level rejections — quota limits, org-policy constraints (e.g. constraints/iam.disableServiceAccountKeyCreation, which this module's own design already respects by never creating a key), or the eventual-consistency behavior noted in Architecture Notes. Only a real terraform plan/apply against a live project, with valid credentials, exercises those paths — that step belongs to the consuming CI pipeline, not this authoring session.

$ terraform output

email = "orders-api@casey-prod-workloads.iam.gserviceaccount.com"
id = "projects/casey-prod-workloads/serviceAccounts/orders-api@casey-prod-workloads.iam.gserviceaccount.com"
member = "serviceAccount:orders-api@casey-prod-workloads.iam.gserviceaccount.com"
name = "projects/casey-prod-workloads/serviceAccounts/orders-api@casey-prod-workloads.iam.gserviceaccount.com"
unique_id = "114522374981726543210"

• google_service_account provider resource reference
• terraform-google-project-iam-bindings (primary consumer of this module's member/email outputs)
• terraform-google-project-services (must enable iam.googleapis.com before this module applies)
• This module's SCOPE.md