GCP Deployment Prerequisites

Use this page as a deploy readiness checklist before running helm upgrade on bighammer.

For provisioning methods, Terraform/Bicep modules, and reference values from your IaC repository, see Infrastructure.

GCP foundation (must exist)

Resource	Purpose
GKE	Run platform and AI Agent workloads
Cloud SQL (PostgreSQL)	Application and Keycloak data
Secret Manager	Passwords, TLS, app secrets
Cloud DNS	Resolve ingress hostnames
GCS	Schemas and artifacts
Artifact Registry	Container images
Workload Identity SAs	ESO + application pod access to GCP APIs

Minimum configuration

Area	Requirement
GKE	STABLE release channel; Workload Identity enabled; on-demand node pool ≥ e2-standard-2; GCS FUSE CSI driver enabled
Cloud SQL	PostgreSQL 16; tier ≥ db-custom-2-3840; private IP; SSL client certs required
Databases	bighammer_db_<env> (application) and keycloak_db_<env> (Keycloak server)
DB users	postgres, bh_dev_user, bh_app_user, keycloak_db_user — names must match chart defaults
DB passwords in GSM	Reference Terraform pushes bh-app-user-password, bh-dev-user-password, db-postgres-password, bh-kcdbpwd
DNS	Public or private zone per company policy; A/CNAME records for all global.ingress.*HostName values

Helm coupling

The chart expects a dual-role database model on the application database (e.g. bighammer_db_<env>):

• POSTGRES_USER / POSTGRES_PASSWORD → bh_dev_user — Alembic migrations, create/alter/drop tables
• BH_APP_USER / BH_APP_USER_PASSWORD → bh_app_user — runtime API and worker traffic (DML only)

See Scripts Reference — dual-role services and Secret Manager Secrets.

Keycloak server database — platform provisioning

The Keycloak server (bhkeycloak) uses a separate database and user provisioned by your platform tooling (Terraform, console, or automation) — not bighammer_db_setup.sql:

Resource	Reference name	Chart
Database	keycloak_db_<env>	global.bhkeycloak.env.KC_DB_URL
User	keycloak_db_user	global.bhkeycloak.env.KC_DB_USERNAME
Password (GSM)	bh-kcdbpwd	global.remoteSecrets.keycloak.dbPassword → KC_DB_PASSWORD

If you rename these during provisioning, update all chart touchpoints — Renaming databases or users.

Shared VPC firewall (host project)

If GKE uses Shared VPC, allow on the host project (target: GKE node service account):

Port	Purpose
TCP 10256	Load balancer health checks
TCP 80, 443	HTTPS ingress traffic

Cluster add-ons (install before platform chart)

Add-on	Required	Helm chart [BigHammer tested versions]
External Secrets Operator	Yes	external-secrets-0.18.2
ingress-nginx or Gateway API	Yes (pick one)	Helm chart 4.15.1 (controller v1.15.1) or Envoy Gateway
RabbitMQ (separate Helm release)	Yes	bhrabbitmq (ECR OCI) or existing broker
Stakater Reloader	Recommended	reloader-1.1.0
Cert Manager	Only for TLS Option A	cert-manager-v1.19.2

IAM (minimum roles)

Principal	Role
ESO GCP service account	roles/secretmanager.secretAccessor
App Workload Identity SA	roles/secretmanager.secretAccessor (or scoped equivalent)
GKE node service account	roles/artifactregistry.reader
CI/CD service account	roles/artifactregistry.writer; roles/dns.admin if using DNS-01 TLS

Service account names and WI bindings: Workload Identity · full IAM in Infrastructure.

Tools

Tool	Version
gcloud	Latest stable
kubectl	Matches cluster version
helm	3.10+
psql	For database bootstrap SQL

Optional platform services

Not required for the core Helm chart, but used in the reference GCP environment:

Service	Purpose
Cloud Composer	Airflow orchestration
Dataproc	Spark jobs from Composer
Vertex AI	Chat LLMs (Claude, Gemini) for bhaiagent — see Vertex AI (LLM)

Details: Infrastructure · Architecture.

Next steps

1. Provision foundation — Infrastructure
2. Mirror entitled artifacts — Release Manifest & Distribution
3. Prepare the cluster — Cluster preparation
4. Deploy chart — Platform Deployment · Deployment Checklist