Skip to main content

​
Firestore Prerequisites and Precheck

​
Purpose

Validate Firestore readiness for production services that require exactly-once coordination.

​
When to run this

  • Before deploying Phase 8S+ ledger/exactly-once changes
  • During deploy verification when api/** changed
  • During incident triage for Firestore preflight failures

​
Prerequisites

  • gcloud authenticated to project payroll-bi-gauntlet
  • Admin JWT available for preflight endpoint checks
  • Cloud Run services deployed and reachable

​
Inputs

  • Project: payroll-bi-gauntlet
  • Region: us-central1
  • Services:
    • payroll-backend-prod (System of Record API)
    • payroll-pipeline-cbs-api (Config Plane API)

​
Procedure

​
1) Enable Firestore API

gcloud services enable firestore.googleapis.com --project=payroll-bi-gauntlet

​
2) Verify Firestore database exists

gcloud firestore databases list --project=payroll-bi-gauntlet
Expected: Native-mode Firestore database exists in us-central1.

​
3) Verify runtime IAM

gcloud projects get-iam-policy payroll-bi-gauntlet \
  --flatten="bindings[].members" \
  --filter="bindings.members:sa-worker@payroll-bi-gauntlet.iam.gserviceaccount.com AND bindings.role:roles/datastore.user"
Expected: binding includes roles/datastore.user for runtime service account.

​
4) Resolve both service URLs

gcloud run services describe payroll-backend-prod \
  --region=us-central1 \
  --project=payroll-bi-gauntlet \
  --format="value(status.url)"

gcloud run services describe payroll-pipeline-cbs-api \
  --region=us-central1 \
  --project=payroll-bi-gauntlet \
  --format="value(status.url)"

​
5) Run preflight on both services

curl -s -H "Authorization: Bearer <ADMIN_JWT>" \
  https://<SYSTEM_OF_RECORD_URL>/api/v1/admin/firestore-preflight

curl -s -H "Authorization: Bearer <ADMIN_JWT>" \
  https://<CONFIG_PLANE_URL>/api/v1/admin/firestore-preflight
Expected: 200 with {"ok": true} from both endpoints.

​
Verification

  • Firestore API enabled
  • Firestore database exists in expected region/mode
  • Runtime service account has roles/datastore.user
  • Preflight passes on both Cloud Run services

​
Failure modes & fixes

  • FirestorePreflightFailed
    • Confirm API enabled and database exists.
    • Confirm runtime SA IAM includes roles/datastore.user.
  • 401/403 on preflight endpoint
    • Verify admin JWT validity and role claims.
  • Only one service passes preflight
    • Recheck service revision/environment parity and runtime SA wiring.

​
Artifacts produced

  • Firestore readiness evidence for both production services
  • Command output proving API/DB/IAM preconditions