Cluster preparation

Configure cluster add-ons, secrets, identity, and edge routing on GKE before installing the BigHammer Helm chart (bighammer). This section covers everything the application chart depends on but does not install itself.

Before you start

Complete Infrastructure provisioning (GKE, Cloud SQL, Secret Manager, DNS, Artifact Registry) and the Prerequisites checklist first.

Recommended order

Order	Page	Purpose
1	Workload Identity	Bind KSAs to GCP service accounts (ESO + apps)
2	External Secrets Operator	Install ESO to sync Secret Manager → Kubernetes
3	TLS Options	SSL/TLS certificates for HTTPS at the edge
4a	NGINX Ingress Deployment	Legacy edge — single Ingress resource
4b	Gateway API Deployment	Recommended edge — Envoy Gateway + Gateway API
4b-i	bh-gateway	Platform Gateway / EnvoyProxy (Gateway API path)
5	RabbitMQ broker	Deploy bhrabbitmq (OCI), Bitnami, or use an existing broker
6	Secret Manager Secrets	GSM name mapping and global.remoteSecrets reference
7	CD deployment (Gateway mode)	GitHub Actions runner RBAC for HTTPRoute (if using CI/CD)

Pick one edge mode in step 4 — nginx or Gateway API. Gateway API is recommended for new deployments. Deploy RabbitMQ after edge setup (step 5) when using Gateway API management UI — see RabbitMQ broker. When Gateway mode is enabled, complete step 7 before the first automated bighammer deploy from GitHub Actions.

Database bootstrap and GSM timing

Run bighammer_db_setup.sql and bh_gsm_onetime_setup.sh from Scripts Reference after Cloud SQL is provisioned and before Helm install. Platform GSM passwords must already exist in Secret Manager; the script verifies them and creates one-time application secrets.

Install Workload Identity and ESO (steps 1–2 above) before the platform chart syncs secrets. The Secret Manager Secrets page is a mapping reference — not a step to defer until after RabbitMQ.

Cluster add-ons (summary)

From Prerequisites — install before the platform chart:

Add-on	Helm chart
External Secrets Operator	external-secrets-0.18.2
Stakater Reloader	reloader-1.1.0
RabbitMQ	bhrabbitmq (OCI) or existing broker
cert-manager	cert-manager-v1.19.2 (TLS Option A only)
Edge	ingress-nginx Helm 4.15.1 or Envoy Gateway + bh-gateway

CD deployment requirements (Gateway mode)

When global.gateway.enabled: true on the bighammer chart (and on standalone charts that expose HTTPRoute templates), Helm deploys HTTPRoute resources in API group gateway.networking.k8s.io instead of (or in addition to) Ingress objects.

GitHub Actions CD workflows (cd-deploy-bighammer-gke-dev, etc.) run helm upgrade using the in-cluster runner identity:

system:serviceaccount:github-runner:github-runner-sa

That service account must be allowed to get, create, update, and delete Gateway API resources. Permission for networking.k8s.io/ingresses does not cover gateway.networking.k8s.io/httproutes.

Symptom if RBAC is missing

httproutes.gateway.networking.k8s.io "bhui-route" is forbidden:
User "system:serviceaccount:github-runner:github-runner-sa" cannot get resource "httproutes"

Manual helm with an admin kubeconfig may still work; only the pipeline fails.

Fix (cluster admin — once per cluster)

Apply the runner ClusterRole from bh-helm-charts (includes Gateway API rules):

kubectl apply -f scripts/github-actions-runner-gcp/runner-role.yaml
kubectl apply -f scripts/github-actions-runner-gcp/runner-rolebinding.yaml

Repository path: bh-helm-charts/scripts/github-actions-runner-gcp/.

Minimum additional rules (if patching an existing role):

- apiGroups: ["gateway.networking.k8s.io"]
  resources: ["httproutes", "gateways", "referencegrants"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["gateway.networking.k8s.io"]
  resources: ["httproutes/status", "gateways/status"]
  verbs: ["get", "update", "patch"]

Verify

kubectl auth can-i get httproutes \
  --as=system:serviceaccount:github-runner:github-runner-sa \
  -n bh-control-plane
# expected: yes

kubectl auth can-i create httproutes \
  --as=system:serviceaccount:github-runner:github-runner-sa \
  -n bh-control-plane
# expected: yes

When this step is required

Edge mode	Runner needs Gateway API RBAC?
nginx (global.ingress.enabled: true)	No — ingresses only
Gateway (global.gateway.enabled: true)	Yes — before first CD deploy

Nginx-only CD

If you stay on nginx Ingress and do not enable gateway mode, the existing runner ClusterRole is sufficient; skip this section.

What to do next

When TLS, secrets, Workload Identity, and edge routing are in place:

1. Platform Deployment — helm upgrade the bighammer chart
2. Deployment Checklist — final verification
3. Troubleshooting — if something fails

For customer artifact access and release pins, see Release Manifest & Distribution.