bh-gateway (platform edge)

Deploy the BigHammer platform edge on Gateway API: shared Gateway, EnvoyProxy, ClientTrafficPolicy, and ReferenceGrant resources that application HTTPRoute objects attach to.

Prerequisites: Complete Gateway API Deployment Steps 1–2 (CRDs + Envoy Gateway controller) before running the commands below.

kubectl get pods -n envoy-gateway-system -l app.kubernetes.io/name=envoy-gateway

Install from OCI (Helm)

1. Set chart location and version

BigHammer publishes the chart to AWS ECR (OCI). Mirror to your GAR via the reader role.

# BigHammer ECR (reference)
export BH_GATEWAY_CHART=oci://<bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com/gcp/bh-helm-release/bh-gateway
export CHART_VERSION=1.0.0

# Customer GAR (after promotion) — example
# export BH_GATEWAY_CHART=oci://us-east1-docker.pkg.dev/<project>/bh-helm-release/bh-gateway

Pin CHART_VERSION to the tag approved for your environment.

2. Authenticate to the registry

ECR:

aws ecr get-login-password --region <bh-catalog-aws-region> | \
  helm registry login --username AWS --password-stdin <bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com

GAR:

gcloud auth print-access-token | \
  helm registry login --username oauth2accesstoken --password-stdin https://<region>-docker.pkg.dev

3. Prepare a values overlay

Create a file on your workstation (for example values-gcp.yaml). Minimum fields for GKE:

# values-gcp.yaml — customer / environment overlay

labels:
  env: prod

gateway:
  listeners:
    https:
      tlsSecretName: <env>-gcp-bighammer-tls
      tlsSecretNamespace: bh-control-plane   # App namespace where TLS secret lives

envoyProxy:
  envoyService:
    annotations:
      cloud.google.com/l4-rbs: "enabled"
      cloud.google.com/network-tier: "Standard"
    externalTrafficPolicy: Cluster

referenceGrants:
  routeNamespaces:
    - bh-control-plane

See Configure values for field descriptions. Edge SSL/TLS: TLS Options (Gateway listener paths and shared GSM keys).

4. Install or upgrade

helm upgrade --install bh-gateway "${BH_GATEWAY_CHART}" \
  --version "${CHART_VERSION}" \
  -f values-gcp.yaml \
  -n envoy-gateway-system \
  --force-conflicts

Flag	Purpose
Release name `bh-gateway`	Must match the Gateway resource name apps reference in `parentRef`
Namespace `envoy-gateway-system`	Same namespace as Envoy controller and platform `Gateway`
`--force-conflicts`	Safe server-side apply when Gateway API fields are managed by multiple controllers on GKE

Use --create-namespace only if envoy-gateway-system does not exist (normally created in Gateway API Step 2).

5. Verify before continuing

kubectl get gateway bh-gateway -n envoy-gateway-system
kubectl describe gateway bh-gateway -n envoy-gateway-system
kubectl get svc -n envoy-gateway-system -o wide
kubectl get referencegrant -n envoy-gateway-system

Ready to proceed when:

Gateway status is Programmed
Data-plane LoadBalancer Service has an EXTERNAL-IP (name like envoy-envoy-gateway-system-bh-gateway-*)
GCP load balancer backend health is healthy (TCP 10256 — see GKE load balancer)
TLS secret exists: kubectl get secret <tlsSecretName> -n <tlsSecretNamespace>

6. Upgrade after value changes

Edit values-gcp.yaml, then re-run the same helm upgrade --install command. No CRD or controller reinstall is required for TLS, LB, or namespace grant changes.

What to do next

DNS — Point hostnames (ui.*, catalog.*, kc.*, …) to the data-plane EXTERNAL-IP from Step 5.
Deploy BigHammer with Gateway mode enabled:

global:
  ingress:
    enabled: false
  gateway:
    enabled: true
    parentRef:
      name: bh-gateway
      namespace: envoy-gateway-system
      sectionName: https

Follow Platform Deployment and Deployment Checklist.
Confirm routes: kubectl get httproute -n bh-control-plane
Smoke test: curl -kI https://<your-ui-hostname>

Overview

What this chart installs

Resource	Purpose
`GatewayClass`	Binds listeners to the Envoy Gateway controller
`Gateway` (`bh-gateway`)	Public HTTP/HTTPS listeners; TLS termination on Envoy
`EnvoyProxy` (`bh-envoy-proxy`)	Data-plane Envoy Deployment + external LoadBalancer
`ClientTrafficPolicy`	Edge timeouts and connection limits
`ReferenceGrant`	Permits `HTTPRoute` in listed namespaces to attach to `bh-gateway`

What this chart does not install

Gateway API or Envoy Gateway CRDs → Gateway API Step 1
Envoy Gateway controller → Gateway API Step 2
Application workloads or HTTPRoute definitions → Platform Deployment

Where this fits in the full stack

Step	Doc	Release
1	Gateway API — CRDs	Upstream `gateway-crds-helm` (OCI)
2	Gateway API — Controller	Upstream `gateway-helm` (OCI)
3	This page	`bh-gateway` (OCI) in `envoy-gateway-system`
4	Platform Deployment	`bighammer` (apps + HTTPRoutes)

Helm release contract

Item	Value
OCI chart	`oci://…/gcp/bh-helm-release/bh-gateway`
Release name	`bh-gateway`
Namespace	`envoy-gateway-system`
Gateway resource	`bh-gateway`
GatewayClass	`eg`
HTTPS listener	`sectionName: https`

TLS certificates usually live in the application namespace (for example bh-control-plane) and are referenced cross-namespace by the Gateway listener.

Configure values

Core gateway and TLS

gateway:
  enabled: true
  provider: envoy
  createNamespace: false          # Envoy controller install (Step 2) owns the namespace
  name: bh-gateway
  namespace: envoy-gateway-system
  gatewayClassName: eg              # Must match Envoy Gateway GatewayClass
  listeners:
    http:
      enabled: true                 # Optional HTTP listener (port 80)
      port: 80
    https:
      enabled: true
      port: 443
      mode: Terminate               # TLS on Envoy; GCP LB is L4 passthrough
      tlsSecretName: <env>-gcp-bighammer-tls
      tlsSecretNamespace: bh-control-plane

GKE load balancer and network tier

The Envoy data-plane Service is type LoadBalancer. On GKE, use these settings in your values overlay:

envoyProxy:
  name: bh-envoy-proxy
  envoyService:
    type: LoadBalancer
    annotations:
      cloud.google.com/l4-rbs: "enabled"
      cloud.google.com/network-tier: "Standard"
    externalTrafficPolicy: Cluster
    allocateLoadBalancerNodePorts: false
  envoyDeployment:
    replicas: 2

Setting	Why it matters
`cloud.google.com/l4-rbs: "enabled"`	GKE L4 regional passthrough NLB. TLS terminates on Envoy, not on the GCP load balancer.
`cloud.google.com/network-tier: Standard`	Standard tier external IP (reference dev pattern). Use `Premium` if your org requires it.
`externalTrafficPolicy: Cluster`	Health checks on kube-proxy port 10256 — same as ingress-nginx and existing Shared VPC firewall rules.
`allocateLoadBalancerNodePorts: false`	Avoids extra NodePorts with Cluster policy + L4 RBS.

GKE health checks

Do not set the GCP health-check port to 80 or 443. With externalTrafficPolicy: Cluster, checks must use TCP 10256.

On Shared VPC, allow 10256 from Google ranges (130.211.0.0/22, 35.191.0.0/16, …) on the host project. Allow 80 and 443 for client traffic — see Prerequisites.

Controller vs data-plane — do not mix them up:

Service	Type	Use for DNS?
`envoy-gateway`	ClusterIP	No — internal controller only
`envoy-envoy-gateway-system-bh-gateway-*`	LoadBalancer	Yes — `EXTERNAL-IP` for A records

HTTPRoute namespaces (ReferenceGrant)

Only namespaces in referenceGrants.routeNamespaces may attach HTTPRoute resources to bh-gateway:

referenceGrants:
  routeNamespaces:
    - bh-control-plane
    - spark-operator
  crossNamespace:
    # HTTPRoute in bh-control-plane → RabbitMQ Service in another namespace
    - routeNamespace: bh-control-plane
      backendNamespace: messaging

RabbitMQ in a separate namespace: add crossNamespace as above, redeploy bh-gateway, deploy the broker, then enable global.gateway.routes.bhrabbitmq with backendRef.namespace: messaging. See RabbitMQ broker — Cross-namespace.

Add a namespace before deploying HTTPRoutes from that namespace, then run helm upgrade again.

Ongoing changes

You need to…	Edit	Re-run
TLS secret or listener ports	`gateway.listeners.https`	`helm upgrade bh-gateway` (OCI + values file)
LB tier or traffic policy	`envoyProxy.envoyService`	Same
Allow HTTPRoutes from new namespace	`referenceGrants.routeNamespaces`	Same
Cross-namespace HTTPRoute → Service	`referenceGrants.crossNamespace`	Same — RabbitMQ example
App hostnames or paths	`global.gateway.routes` in `bighammer`	`helm upgrade bighammer` only
Envoy Gateway version	Upstream CRDs + controller	Gateway API Steps 1–2

Troubleshooting

Symptom	Likely cause	Action
Gateway not Programmed	Controller or CRDs missing	Complete Gateway API Steps 1–2
LB 0% healthy	Firewall or wrong health port	TCP 10256 on Shared VPC host project
HTTPS certificate error	TLS secret missing or wrong NS	Match `tlsSecretName` / `tlsSecretNamespace`
HTTPRoute not attached	Namespace not granted	Add to `routeNamespaces`; upgrade chart
`helm upgrade` auth failure	Registry login expired	Re-run ECR or GAR `helm registry login`
No `EXTERNAL-IP`	LB provisioning / quota	Wait; check GCP quotas and subnet

See also Troubleshooting and Gateway API load balancer notes.

Gateway API Deployment — CRDs and Envoy controller
Release Manifest & Distribution — Reader role and artifact mirror
TLS Options — Certificates for the HTTPS listener
Platform Deployment — Apps and HTTPRoutes (Step 4)

Install from OCI (Helm)​

1. Set chart location and version​

2. Authenticate to the registry​

3. Prepare a values overlay​

4. Install or upgrade​

5. Verify before continuing​

6. Upgrade after value changes​

What to do next​

Overview​

What this chart installs​

What this chart does not install​

Where this fits in the full stack​

Helm release contract​

Configure values​

Core gateway and TLS​

GKE load balancer and network tier​

HTTPRoute namespaces (ReferenceGrant)​

Ongoing changes​

Troubleshooting​

Related​