Setup guide

Read and set IAM policy on the organization node, and create the org-level bindings the landing zone depends on.

↳ For read-only discovery (`gcloud organizations get-iam-policy`, asset searches) roles/resourcemanager.organizationViewer plus roles/iam.securityReviewer is enough; only the apply phase needs organizationAdmin.

Create the /prod, /nonprod, /common, /bootstrap folder hierarchy at the org node.

↳ roles/resourcemanager.folderAdmin also grants delete and setIamPolicy on folders; folderCreator is the narrower choice for a pure build-out.

Create the seed project, the per-environment Shared VPC host projects, and every workload service project.

↳ Grant at the folder rather than the organization once the hierarchy exists, so the CI identity cannot create projects outside its own folder.

Link new projects to the billing account, turn on the BigQuery billing export, and create budgets.

↳ Split it: roles/billing.user on the billing account plus roles/resourcemanager.projectBillingManager on the folder covers linking, and roles/billing.costsManager covers budget create/update without full admin.

Set and dry-run the org policy baseline (iam.disableServiceAccountKeyCreation, compute.vmExternalIpAccess, gcp.resourceLocations, storage.publicAccessPrevention, and the rest).

↳ Simulation and read-back only need roles/orgpolicy.policyViewer plus roles/policysimulator.admin; hold policyAdmin only for the enforcing apply.

Create the aggregated organization sink with include_children=true and its exclusion filters.

↳ roles/logging.viewer suffices to audit existing sinks; configWriter is only needed for create/update.

Enable each environment's project as a Shared VPC host and attach service projects to it.

↳ Must be granted at the organization or folder — it cannot be granted at project scope. Once hosts exist, day-2 subnet grants only need roles/compute.networkAdmin on the host project.

Define org-level custom roles for the few cases where the closest predefined role carries roughly twice the permissions needed.

↳ Skip entirely if you can live with predefined roles — the skill's own guidance is to prefer predefined roles.

Create the org-node IAM deny policy that backstops service-account-key creation, since deny is evaluated before allow and no project-level grant can override it.

↳ roles/iam.denyReviewer gives read-only visibility into existing deny policies for audit work.

Create the CI workload identity pool and the GitHub OIDC provider with its mandatory attribute condition, so CI never needs a service account key.

↳ Grant on the seed project only, never at the org node.

Batch-enable cloudresourcemanager, cloudbilling, iam, orgpolicy, compute, logging, storage, cloudasset, and billingbudgets APIs on the seed and host projects.

↳ roles/serviceusage.serviceUsageConsumer is enough at runtime once the APIs are on.

Create the versioned Terraform state bucket with uniform bucket-level access and public access prevention.

↳ Grant on the seed project only. After creation, the CI runner needs just roles/storage.objectAdmin on that single bucket to read and write state.

Export the org-wide resource baseline and run `searchAllIamPolicies` to hunt residual roles/owner bindings.

↳ Grant at the org node for full-estate visibility, or at a single folder if the review is scoped to one environment.

Read IAM policy recommendations after 60-90 days of real traffic to trim over-broad bindings.

↳ roles/recommender.iamAdmin is only needed if you want to mark recommendations as claimed/succeeded from automation.

Granted to the log sink's returned writer_identity on the destination dataset — without it the sink silently drops every record.

↳ Grant on the single destination dataset via google_bigquery_dataset_iam_member, never at project scope. For a GCS destination the equivalent is roles/storage.objectCreator on the one bucket.

Granted to each workload's Google Group so service-project VMs can attach to the Shared VPC subnet.

↳ Always grant at SUBNET scope (`gcloud compute networks subnets add-iam-policy-binding`), never at host-project scope — project scope hands the team every subnet in the VPC.

The OAuth scope gcloud and the Terraform google provider request for every Resource Manager, Org Policy, Billing, Compute, Logging, and Asset Inventory call in this skill.

↳ https://www.googleapis.com/auth/cloud-platform.read-only covers the discovery and audit phases (org list, asset search, policy read-back) but not any create or set operation.

Cause: The caller holds project-level roles only; org-node bindings require roles/resourcemanager.organizationAdmin, which on a fresh org only a Cloud Identity super admin can grant to themselves first.

Fix: Have a Cloud Identity super admin open Cloud Console with the ORGANIZATION selected in the resource picker, IAM & Admin > IAM > GRANT ACCESS, and add Organization Administrator to your group. Re-check with `gcloud organizations get-iam-policy "$ORG_ID"`. Note the '(or it may not exist)' suffix is generic — it usually means denied, not missing.

Cause: ADC from `gcloud auth application-default login` has no quota project, and the Terraform google provider was not given one either.

Fix: Run `gcloud auth application-default set-quota-project "$SEED"` and set `billing_project = var.seed_project_id` with `user_project_override = true` in the provider block. This is the single most common Terraform failure on org-level resources.

Cause: Missing roles/orgpolicy.policyAdmin, or the policy name/parent is a folder the caller only has projectCreator on.

Fix: Grant roles/orgpolicy.policyAdmin at the org node (it does not inherit downward from a project grant) and confirm the resource `parent` string is exactly `organizations/ORG_ID` or `folders/FOLDER_ID`, not a project.

Cause: Step 5 of the skill enforces iam.disableServiceAccountKeyCreation org-wide, so any attempt to mint a JSON service account key for CI is rejected by design.

Fix: Do not create a key. Use Workload Identity Federation with `gcloud iam workload-identity-pools create-cred-config` and point GOOGLE_APPLICATION_CREDENTIALS at that external_account file. If you truly need a temporary exception, add a child org policy on the bootstrap folder with inherit_from_parent = true and an allow rule — never delete the parent policy.

Cause: `gcloud iam workload-identity-pools providers create-oidc` was given an --attribute-mapping containing attribute.repository (or any non-subject attribute) without a matching --attribute-condition, which Google blocks because it would let any repo on the issuer assume the identity.

Fix: Add `--attribute-condition="assertion.repository=='ORG/REPO'"` (single quotes inside, matching a claim actually present in the mapping). See https://cloud.google.com/iam/help/workload-identity/attribute-condition.

Cause: The billing account is closed or the caller lost roles/billing.user, so `gcloud billing projects link` silently left the project unlinked and the next API call fails.

Fix: Confirm `gcloud billing accounts describe "$BILLING_ID" --format='value(open)'` returns True, re-run `gcloud billing projects link "$SEED" --billing-account="$BILLING_ID"`, and verify with `gcloud billing projects describe "$SEED"`.

Cause: Bulk-creating dozens of workload projects in one apply hits the per-minute project creation rate limit, and separately the billing account has a hard cap on total projects.

Fix: Request a project-creation quota increase at IAM & Admin > Quotas BEFORE the build, then throttle Terraform with `terraform apply -parallelism=5` and split project creation into its own state layer so a retry does not re-plan the org.

Cause: Running gcloud or Terraform from a Compute Engine VM whose default service account was created with restricted OAuth scopes, so cloud-platform is not granted regardless of IAM roles.

Fix: Recreate the runner VM with `--scopes=https://www.googleapis.com/auth/cloud-platform`, or better, run CI through Workload Identity Federation instead of a VM's default service account.

Cause: gcp.resourceLocations was scoped by enumerating individual regions, which blocks multi-region GCS buckets, some Cloud Build workers, and global load balancer components.

Fix: Replace the enumerated region list with a value group such as `in:us-locations` in the allowed_values list, then re-run `gcloud org-policies describe constraints/gcp.resourceLocations --organization="$ORG_ID" --effective`.

Cause: Usually a missing enabled API on the quota/billing project, an unlinked billing account, or the org policy compute.skipDefaultNetworkCreation interacting with auto_create_network.

Fix: Enable cloudresourcemanager.googleapis.com, cloudbilling.googleapis.com, and serviceusage.googleapis.com on the seed project, confirm billing is linked, and set `auto_create_network = false` on every google_project resource.

Cause: Missing roles/logging.configWriter at the org node; a project-level grant does not cover organizations.sinks.create.

Fix: Grant roles/logging.configWriter on the organization. Separately, after creation grant the sink's writer_identity roles/bigquery.dataEditor on the destination dataset or the sink will accept writes and drop every record.

Cause: The default ceiling of roughly 100 service projects per Shared VPC host project was reached.

Fix: Add a second host project for that environment or region, or request a Shared VPC quota increase at IAM & Admin > Quotas well before you approach the limit — moving a host project after service projects attach is disruptive.