Skip to content

GCP organization

Org tomoda.life (id 650647255726) holds one project, development-485000, and no folders. Billing account TomodaBillingAcc (01CBC0-F49F57-C4BF88) pays for it. Project resources live in the GCP stack; this page covers what sits above the project.

Terraform: infrastructure/gcp-org/, state in gs://tomoda-tfstate under gcp-org/state. CI plans it on PRs; an org owner applies it locally. CI never applies it: the apply identity is project-scoped.

Managed by Terraform

Resource File Notes
Org owners: roles/owner and roles/resourcemanager.organizationAdmin org_iam.tf (local.org_owners) prevent_destroy; plan fails with fewer than 2 owners. See Ownership and break-glass
Org IAM: every other human, group and domain grant org_iam.tf (local.org_members) Additive google_organization_iam_member. Groups get their org roles here; membership does not
Billing account IAM billing.tf (local.billing_members) Additive google_billing_account_iam_member
Budget billing threshold billing.tf Whole account, CAD 100/month, alerts at 50/90/100%
Budget development-485000 monthly billing.tf Project only, CAD 25/month, alerts at 50/90/100%

Budgets email the billing account's admins and users. They only notify; nothing stops spend.

Access model

  • Terraform declares the grants that should exist. Only org owners hold project-power roles at the org, because org grants inherit into every project and override per-project grants. Everyone else gets project access in infrastructure/gcp/people.tf.
  • A grant Terraform manages is removed by deleting it from config; the apply destroys it.
  • A grant Terraform never managed (made by hand, or left over from setup) is revoked once by hand with gcloud organizations remove-iam-policy-binding, and is simply never added to config.

The exact grants are in org_iam.tf.

Manual, and why

Item Why
Google service-agent grants (service-org-…@…) Created and owned by Google; editing them breaks the service
Group membership (gcp-*@tomoda.life) Managed in Workspace admin (Directory → Groups). The Cloud Identity API is off, so Terraform cannot read or manage it; check membership there when auditing
Org policies (8 at org level, 2 project overrides) Unchanged since setup; can be imported with google_org_policy_policy when one needs to change
Closed billing account My Billing Account (01E6D9-36A01A-88BBF9) Closed, no projects linked
_Default / _Required log sinks and buckets Google defaults

Who applies it

Identity Roles Does
terraform-ci (CI, WIF), plan Org roles/iam.securityReviewer, roles/resourcemanager.organizationViewer; billing account roles/billing.viewer terraform plan on PRs
An org owner (laptop, ADC) Org owner terraform apply locally after merge

CI does not apply this stack. Applying needs org roles/iam.securityAdmin (IAM write on the whole org, including roles/owner) and billing roles/billing.costsManager; terraform-apply is project-scoped and gets neither.

The plan read roles are granted by hand once, outside this stack, so terraform-ci never manages its own org access:

gcloud organizations add-iam-policy-binding 650647255726 \
  --member=serviceAccount:terraform-ci@development-485000.iam.gserviceaccount.com \
  --role=roles/iam.securityReviewer --condition=None
gcloud organizations add-iam-policy-binding 650647255726 \
  --member=serviceAccount:terraform-ci@development-485000.iam.gserviceaccount.com \
  --role=roles/resourcemanager.organizationViewer --condition=None
gcloud billing accounts add-iam-policy-binding 01CBC0-F49F57-C4BF88 \
  --member=serviceAccount:terraform-ci@development-485000.iam.gserviceaccount.com \
  --role=roles/billing.viewer

Until they exist, the plan (gcp-org) job posts a notice and skips.

Applying

After the PR merges, from a clean checkout of main:

gcloud auth application-default login   # as an org owner
cd infrastructure/gcp-org
terraform init
terraform plan -out=org.tfplan          # must match the plan posted on the PR
terraform apply org.tfplan

The stack bills API quota to development-485000 and needs cloudbilling and billingbudgets enabled there; the GCP stack manages both.

Adding or removing access

  • Add a person or group: add the member (user:…, group:…) and its roles to local.org_members, open a PR, review the plan, merge, apply.
  • Change roles: edit the member's list. Removing a role destroys that one grant on apply.
  • Remove a person: delete their entries in local.org_members and local.billing_members, and their project grants in the GCP stack.
  • Add a person to a gcp-* group: Workspace admin, not this stack. The group's org roles already apply to them.
  • Add or remove an org owner: see Ownership and break-glass.

Org grants are inherited by every project, so an org role on a person applies on development-485000 whatever people.tf says, and org owners need no project-level owner grant. Grant through this stack, not the Console: a hand-made grant is invisible here and survives offboarding.

Ownership and break-glass

  • Owners are the users in local.org_owners. Each gets roles/owner and roles/resourcemanager.organizationAdmin as separate grants, both prevent_destroy. An output precondition fails the plan if fewer than 2 remain.
  • Ownership changes only through a PR plus a supervised apply by an existing owner. Adding an owner is a normal apply. Removing one fails on prevent_destroy by design: under supervision, terraform state rm both of that user's grants, apply the PR, then remove the grants in the Console.
  • CI cannot change ownership: terraform-ci holds only read roles at the org, and terraform-apply none.
  • Break-glass: a Google Workspace super admin for tomoda.life can always recover GCP org access (grant themselves organizationAdmin in the Console), even if every owner grant is lost. Keep at least 2 Workspace super admins, each with 2-step verification enforced. That is set in the Workspace admin console, not Terraform.