IAM¶
Who and what can authenticate where. Workloads in the cluster hold no cloud identity of their own: every credential reaches them as a Kubernetes Secret synced by External Secrets from GCP Secret Manager.
Credentials the cluster uses¶
| Credential | Source (GCP SM) | Lands as | Grants |
|---|---|---|---|
| ESO reader key | none (hand-created at bootstrap) | external-secrets/gcpsm-credentials |
roles/secretmanager.secretAccessor on development-485000 |
| R2 cluster token | tomoda-r2-cluster-credentials |
data/r2-backup-credentials, monitoring/r2-observability-credentials, Xavia OTA env, r2-seed-credentials |
Object read/write on tomoda-db-backups, tomoda-observability, tomoda-ota-*, tomoda-location-seed, tomoda-photon-index |
| R2 app token (per env) | tomoda-r2-app-{env}-credentials |
tomoda-{env}/object-storage-credentials |
Object read/write on tomoda-assets-{env} only |
| Asset signing key (per env) | tomoda-asset-signing-key-{env} |
backend-secrets-{env} (ASSET_SIGNING_KEY), assets Worker secret |
Minting media URLs the Worker accepts |
| GHCR read token | tomoda-ghcr-read-credentials |
k3s registries.yaml on each node, argocd/ghcr-image-updater, tomoda-{env}/ghcr-pull |
read:packages |
| GitHub App | tomoda-github-app-* |
argocd/repo-devops, ARC, trivy-issue-reporter |
Repo read, runners, issues |
| Cloudflare API token | tomoda-cloudflare-api-token |
Terraform CI, external-dns, cert-manager DNS-01 | DNS, Workers, R2, Access edit on the zone/account |
Scope each R2 token to its buckets in the Cloudflare dashboard (R2 → Manage API tokens → Apply to specific buckets only). Rotate by creating a new token, updating the GCP SM value, waiting for ESO's 1h refresh (or deleting the ExternalSecret to force it), then revoking the old token.
GCP service accounts¶
eso-reader¶
GCP SA: eso-reader@development-485000.iam.gserviceaccount.com
Roles: roles/secretmanager.secretAccessor
Key: stored only as external-secrets/gcpsm-credentials
The single static GCP key in the platform. Rotate yearly: create a new key, replace the cluster Secret with the kubectl create secret ... --dry-run=client -o yaml | kubectl apply -f - line from scripts/ovh/bootstrap-argocd.sh, delete the old key.
terraform-ci¶
The identity Terraform plans run as. GitHub Actions authenticates via Workload Identity Federation and impersonates this SA; no key is stored in GitHub. Any workflow run in the repo can impersonate it, PR branches included, so it holds read roles only. Applies run as terraform-apply.
GCP SA: terraform-ci@development-485000.iam.gserviceaccount.com
Roles:
- roles/viewer, roles/iam.securityReviewer (plan reads, including IAM policies)
- roles/serviceusage.serviceUsageConsumer (quota project for API calls)
- roles/storage.objectViewer on tomoda-tfstate (state; plans run with -lock=false)
- roles/storage.bucketViewer on tomoda-tfstate and tomoda-ios-certs (bucket settings)
- roles/secretmanager.secretAccessor on the plan inputs (local.terraform_ci_plan_secrets)
Impersonated by:
principalSet://…/attribute.repository/tomoda-labs/devops (WIF, this repo only)
Org and billing-account read roles (roles/iam.securityReviewer, roles/resourcemanager.organizationViewer, roles/billing.viewer) let it plan infrastructure/gcp-org/. They are granted by hand, see GCP organization.
These are its full set, managed in infrastructure/gcp/service_accounts.tf. A write role on it that appears outside that file is unmanaged and should be removed. The plan inputs include the Cloudflare, Tailscale and GitHub App credentials, which can write; that is an accepted risk, see Terraform CI/CD.
terraform-apply¶
The identity terraform-apply.yml runs as on main.
GCP SA: terraform-apply@development-485000.iam.gserviceaccount.com
Roles:
- roles/storage.admin on tomoda-tfstate and tomoda-ios-certs
- roles/secretmanager.admin, roles/resourcemanager.projectIamAdmin,
roles/iam.serviceAccountAdmin, roles/iam.workloadIdentityPoolAdmin,
roles/serviceusage.serviceUsageAdmin, roles/serviceusage.apiKeysAdmin
Impersonated by:
principalSet://…/attribute.workflow/tomoda-labs/devops/.github/workflows/terraform-apply.yml@refs/heads/main
attribute.workflow maps the OIDC job_workflow_ref claim, which names the repo, the workflow file and the ref it ran from. PR runs (refs/pull/…), other branches (including a workflow_dispatch on one) and other workflow files never match. It holds no org roles: gcp-org is applied locally.
tomoda-release¶
The identity release workflows on main read their credentials as.
GCP SA: tomoda-release@development-485000.iam.gserviceaccount.com
Roles:
- roles/secretmanager.secretAccessor on tomoda-release-app-private-key and tomoda-ota-prod-upload-key
Impersonated by (WIF, attribute.workflow = job_workflow_ref):
pool github-actions: tomoda-labs/devops/.github/workflows/notify-prod-deploy.yml@refs/heads/main
pool github-actions-tomoda: tomoda-labs/tomoda/.github/workflows/release.yml@refs/heads/main
tomoda-labs/tomoda/.github/workflows/ota.yml@refs/heads/main
The github-actions-tomoda provider accepts only tomoda-labs/tomoda tokens whose ref is refs/heads/main. ota.yml is bound on its own because a called workflow's job_workflow_ref names the called file; the ref condition keeps a branch run from calling it. A workflow_dispatch on a branch or tag, and every PR run, gets no token.
Other service accounts¶
| SA | Roles | Key |
|---|---|---|
play-publisher |
none in GCP; Play Console grants upload rights | tomoda-play-service-account |
firebase-adminsdk-tomoda |
roles/firebase.admin |
Google-managed |
All of these and their grants are in infrastructure/gcp/service_accounts.tf. See GCP.
People¶
Project grants on development-485000 are managed in infrastructure/gcp/people.tf. Org-level grants are in infrastructure/gcp-org/; see Organization and billing.
Each login's project roles are listed in local.people in infrastructure/gcp/people.tf, starting from roles/viewer plus only what the work needs; native releasers also get secretAccessor on the release secrets and read on tomoda-ios-certs. Org owners and the other org grants are in infrastructure/gcp-org/org_iam.tf. Those two files are the exact list.
Org grants apply to every project in the org. Only org owners hold project-power roles there, so for everyone else people.tf is their effective project access (Access model). A non-owner holding roles/resourcemanager.projectIamAdmin can change project IAM outside Terraform; grant it only when needed and check people.tf for who has it.
Organization and billing¶
Org-level IAM on tomoda.life and billing-account IAM are in infrastructure/gcp-org/, applied locally by an org owner. Inventory and onboarding steps: GCP organization.
Auditing¶
# Human org grants (inherited by every project)
gcloud organizations get-iam-policy 650647255726 --format=json \
| jq -r '.bindings[] | .role as $r | .members[] | select(startswith("user:")) | "\(.) \($r)"'
# Project owners + editors
gcloud projects get-iam-policy development-485000 \
--flatten="bindings[].members" \
--filter="bindings.role:roles/owner OR bindings.role:roles/editor" \
--format="table(bindings.members,bindings.role)"
# Keys on the ESO reader (expect exactly one)
gcloud iam service-accounts keys list \
--iam-account=eso-reader@development-485000.iam.gserviceaccount.com --managed-by=user
Review R2 API tokens and Cloudflare account members in the Cloudflare dashboard at the same cadence. See Access control for human access.