Terrakube GCP Ownership

Terrakube is the active remote Terraform control plane for the monorepo GCP root in infra/tf/gcp. The root contains both staging and production workspace selection; the environment determines which Terrakube identity is trusted.

Workspace and identity map

Environment	Terrakube organization	Workspace	Workspace ID	WIF provider ID	Runner service account
Staging	peaksuite (a2f6aba3-b4c7-4dbe-a032-579c15eebadc)	monorepo-staging	22c7acd3-5028-4429-91d0-1f284dec621a	monorepo-staging	tfc-service-account@<staging-project>.iam.gserviceaccount.com
Production	peaksuite (a2f6aba3-b4c7-4dbe-a032-579c15eebadc)	monorepo	3a3ac077-4379-4edc-a35b-78b26c4358bf	monorepo	tfc-service-account@<production-project>.iam.gserviceaccount.com

The issuer is https://iac-api.peaksuite.dev. The service-account name is historical; Terraform sets its display name and description to Terrakube Terraform runner. Do not interpret tfc-service-account as current Terraform Cloud ownership.

infra/tf/gcp/terrakube-wif.tf is authoritative for this mapping. Its provider condition requires both the exact Terrakube organization ID and the environment's workspace ID. The service-account impersonation member is scoped to that workspace attribute in the environment's Workload Identity Pool.

The GCP project ID and number are workspace inputs. Do not copy a staging project or provider resource name into a production operation; resolve the selected Terrakube workspace and its non-secret variables first.

Ownership boundaries

Concern	Owner
GCP resources declared by infra/tf/gcp and its remote state	The matching Terrakube workspace
Terrakube-to-GCP WIF pool, provider, runner service account, and impersonation member	infra/tf/gcp/terrakube-wif.tf (imported and reconciled by the same root)
Backend workspace selection	infra/tf/gcp/backend-staging.hcl (monorepo-staging) and backend-prod.hcl (monorepo)
Terrakube AKS control plane, Helm release, GitHub App integration, and control-plane network	shared-services repository
Monorepo control-plane health detection	.github/workflows/infra-maintenance.yml terrakube-health job
Application/service deployment after infrastructure exists	The owning deployment workflows; Terraform does not automatically own every mutable runtime field

The .hcl files select Terrakube workspaces through the Terraform remote backend. They are not evidence of active Terraform Cloud runs. Never initialize production with the staging backend file or reuse staging workspace variables.

The WIF file creates the identity and trust relationship but does not enumerate every project-level permission required to manage the GCP root. Verify the live service-account IAM policy and the planned operations rather than assuming the runner is project owner.

Credential boundary

Terrakube receives short-lived GCP credentials through OIDC/WIF. It must not receive a checked-in service-account key.

• Keep the Terrakube API token in the approved secret store or local CLI configuration; never print it or commit it.
• Mark secret Terraform variables sensitive in Terrakube. Do not copy values into GitHub issues, plans pasted into chat, or documentation.
• A plan can still expose values when a provider/resource treats them as non-sensitive. Review plan output before sharing it.
• Do not broaden the WIF condition, add a wildcard workspace principal, or grant production impersonation to the staging workspace.
• Changes to the Terrakube control plane belong in shared-services; changes to this repo's GCP resources belong in infra/tf/gcp.

Non-mutating verification

Confirm the selected environment before running these reads. For staging, the current provider and runner can be inspected with:

gcloud iam workload-identity-pools providers describe monorepo-staging \
  --project=peaksuite-staging \
  --location=global \
  --workload-identity-pool=terrakube

gcloud iam service-accounts get-iam-policy \
  tfc-service-account@peaksuite-staging.iam.gserviceaccount.com \
  --project=peaksuite-staging

Expected provider evidence includes the Terrakube issuer and an attribute condition containing the exact organization and staging workspace IDs. Expected service-account evidence includes only the intended workspace-scoped Workload Identity principal for Terrakube impersonation. Additional IAM roles must be evaluated against the root's actual resource operations; this page does not bless them.

Use terrakube job list -o peaksuite only as a capped, read-only overview. The list is not guaranteed to show the newest job for a workspace. In the Terrakube interface, select the exact workspace or job ID and inspect that record manually before drawing a conclusion.

Plan and apply gate

A Plan is the first remote execution after a code, variable, credential, backend, or recovery change. Review:

1. the workspace name, repository branch, and infra/tf/gcp working directory;
2. the selected GCP project and environment;
3. resource replacements, deletions, IAM changes, and state moves/imports;
4. sensitive values or unexpected plaintext in output; and
5. drift outside the intended change.

A Plan and apply mutates infrastructure and requires explicit authorization for the reviewed plan. Never auto-retrigger an apply because the previous job was stuck or because credentials were repaired. Production and staging plans/applies remain separate jobs and state.

Recovery and escalation

The scheduled terrakube-health job checks the OpenTofu release index, GitHub App token freshness, and jobs stuck in a non-terminal state. When it reports a failure:

1. inspect the exact job and step output;
2. classify control-plane failures (release-index fetch, GitHub App token, executor/clone failure) separately from a Terraform plan/apply failure;
3. use the shared-services Terrakube Helm runbook for control-plane repair;
4. cancel a confirmed wedged job before replacement; and
5. run a plan-only job after repair and review the result before any apply.

For a failed workspace plan, fix the source repository or workspace variable that owns the error. Do not recreate deleted service accounts merely to satisfy stale IAM, replace a missing Azure dynamic identity without reviewing its role-assignment drift, or delete state/backend resources as a first response.

Escalate to the shared-services/platform owner when the API, executor, AKS/Helm release, GitHub App installation, or shared network is unhealthy. Escalate to the monorepo infrastructure owner when Terrakube is healthy and the failure is in infra/tf/gcp, its workspace inputs, or GCP IAM/resource drift.