Service Accounts and Keys

A service account is GCP's identity for non-human workloads, and the thing that trips newcomers is that it is two things at once. It is a principal you grant roles to — it appears as a member serviceAccount:event-processor@hatch-app-prod.iam.gserviceaccount.com in other resources' policies. And it is a resource that itself has an IAM policy, controlling who may use or impersonate it. Those are two separate sets of bindings on two different objects, and conflating them is the source of half the confusion in this topic.

The over-privileged defaults are the historical trap. A project's default Compute Engine and default App Engine service account used to be auto-granted roles/editor on the whole project — but for organizations created on or after May 3, 2024, the iam.automaticIamGrantsForDefaultServiceAccounts org policy is enforced by default, so that automatic Editor grant no longer happens; older orgs may still carry it. And service-account keys are downloadable, long-lived secrets with no expiry — they should be your last resort, never your first. Get the two-natures idea and the defaults right, and service accounts stop being mysterious.

An Identity and a Resource

google_service_account creates the account. As an identity, it is a member in other resources' policies — you grant it roles/storage.objectAdmin on the hatch-events-raw bucket so the workload can read and write objects. As a resource, it has its own IAM policy that says who may impersonate it or attach it to a workload. These are two distinct sets of bindings, and people regularly grant on the wrong one: trying to give the SA a bucket role by editing the SA's own policy, or vice versa.

Keeping the two surfaces straight is the whole discipline. "Grant the SA a role" means add the SA as a member on some other resource. "Grant a role on the SA" means edit the SA's own policy to say who may act through it. The configuration below creates the account and then grants it — as an identity — a scoped role on a bucket.

resource "google_service_account" "event_processor" {
  project      = "hatch-app-prod"
  account_id   = "event-processor"
  display_name = "Event pipeline processor"
}

resource "google_storage_bucket_iam_member" "raw_rw" {
  bucket = "hatch-events-raw"
  role   = "roles/storage.objectAdmin"
  member = "serviceAccount:${google_service_account.event_processor.email}"
}

The Email as the Member

The SA's email — here event-processor@hatch-app-prod.iam.gserviceaccount.com — is how you reference it in any binding, prefixed with serviceAccount:. Terraform reads it straight off the google_service_account resource, as in google_service_account.event_processor.email, so you never hardcode the string. Wiring the identity from the resource means a renamed project or a copy-paste slip cannot silently point a binding at the wrong account.

Hardcoding the literal email is the small mistake that causes the large outage. The string looks stable, but the moment a project is renamed or an account recreated under a different ID, the literal is wrong and the binding grants to nothing — or worse, to the wrong identity. Reference the attribute, always.

The Over-Privileged Default Service Accounts

Most projects get two default service accounts — the default Compute Engine SA, <project-number>-compute@developer.gserviceaccount.com, and the App Engine default SA. Historically each was auto-bound roles/editor on the entire project, and where that grant is present anything running on a default VM inherits near-total project access, because the VM runs as that SA and that SA is an editor — the textbook lateral-movement path: pop the VM, inherit project-wide edit. For organizations created on or after May 3, 2024 the iam.automaticIamGrantsForDefaultServiceAccounts constraint is enforced by default, so the automatic Editor grant no longer happens; on older orgs it persists until you remove it or enforce the constraint yourself.

The fix is to create purpose-built service accounts and stop running on the defaults. Remove or replace the default SAs' roles/editor grant, or — better — use an org policy to disable default SA creation entirely, so the dangerous default never exists. A workload should run as an account scoped to exactly what it touches, not as a project-wide editor that happened to come free with the project.

Keys Are a Last Resort

google_service_account_key mints a downloadable JSON private key — a long-lived credential with no expiry. It lands in Terraform state, it leaks from laptops and CI secret stores, and it never rotates itself. It is the credential most likely to end up in a breach report. Prefer impersonation, covered in the next topic, or Workload Identity Federation, and create a key only for the rare external system that genuinely cannot do either.

If you must mint one, treat it as radioactive: it now exists in state that the whole team can read, so the team can read the key. The configuration below shows what to avoid by default — a key resource whose private material is written to state. For anything running inside GCP, you never need this; the workload assumes its attached SA without a key at all.

resource "google_service_account_key" "legacy_export" {
  service_account_id = google_service_account.event_processor.name
  # the JSON private key lands in Terraform state — readable by the whole team,
  # long-lived, never auto-rotated. Prefer impersonation or WIF instead.
}

One Workload, One Service Account

Give event-processor its own service account scoped to exactly the buckets, topics, and datasets it touches, instead of reusing a shared or default SA across unrelated workloads. The payoff is blast-radius containment: a compromise of one workload is limited to that one workload's permissions, not the union of everything a shared account could reach. One workload, one SA, scoped tight — it is the cheapest security control in the chapter and the one most often skipped for convenience.