Skip to content

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.