Gateway API Deployment (Envoy Gateway)

Install Gateway API edge routing on GKE using the upstream Envoy Gateway controller.

Upstream reference: Steps 1–2 follow the official Envoy Gateway — Install with Helm guide (CRDs, controller chart, and GKE compatibility notes).

Scope of this page

This page covers only the Gateway API / Envoy stack (CRDs, controller, platform edge). It does not deploy the BigHammer application chart.

Before you run helm upgrade on bighammer, your cluster must already expose apps through either:

NGINX Ingress, or
The Gateway API stack described here

When to use Gateway API

Choose Gateway API when…	Choose NGINX when…
You want Gateway API `HTTPRoute` resources	You want a single `Ingress` resource
Platform teams manage edge separately from apps	You prefer the simpler nginx pattern
You plan multi-namespace `HTTPRoute` ownership	Gateway API CRDs are not required

Warning : Nginx ingress is not recommended since it is already retired. Please use Gateway API instead. However the legacy stack which is deployed using the nginx controller our chart still supports for backward compatibility.

Architecture — who owns what

The BigHammer Helm chart is fully decoupled from Envoy Gateway. Edge routing is split across independent Helm releases:

Order	Helm release	Chart	Owns
1	`gateway-crds`	Upstream `envoyproxy/gateway-crds-helm` (OCI)	Gateway API + Envoy Gateway CRDs (once per cluster)
2	`eg`	Upstream `envoyproxy/gateway-helm` (OCI)	Envoy Gateway controller in `envoy-gateway-system`
3	`bh-gateway`	`oci://…/gcp/bh-helm-release/bh-gateway`	`GatewayClass`, `Gateway`, `EnvoyProxy`, `ReferenceGrant`, TLS listener (`envoy-gateway-system`)
4	`bighammer`	`bighammer`	Application workloads + `HTTPRoute` resources only

HTTPRoutes live in the BigHammer chart so developers control hostnames, paths, and backends in values-<env>.yaml. Platform edge (Gateway, TLS, LB policy, cross-namespace grants) lives in the bh-gateway chart (Helm release in envoy-gateway-system) and may differ per customer policy.

Default Gateway contract used by BigHammer:

Setting	Value
Gateway name	`bh-gateway`
Gateway namespace	`envoy-gateway-system`
GatewayClass	`eg` (Envoy Gateway default)
HTTPS listener	`sectionName: https`

Prerequisites

Requirement	Notes
GKE cluster with `kubectl` access	Workload Identity and node pool per Infrastructure
`helm` 3.10+	OCI registry support
TLS secret (HTTPS)	Kubernetes secret in app namespace — TLS Options (Ingress vs `bh-gateway` listener)
Shared VPC firewall (if applicable)	TCP 10256 (health checks), 80 / 443 — same as nginx
Envoy Gateway upstream docs	Install with Helm — version matrix, CRD options, chart values

Pin a stable Envoy Gateway version in production. Examples below use 0.0.0-latest (upstream development tag); replace with a release from Envoy Gateway Helm tags when you harden an environment.

Step 1 — Install CRDs

Install Gateway API and Envoy Gateway CRDs separately from the controller. Upstream documents this pattern here: Installing CRDs separately.

Option A — Standard channel (recommended for new clusters)

Applies both Gateway API (standard channel) and Envoy Gateway CRDs:

helm pull oci://registry-1.docker.io/envoyproxy/gateway-crds-helm --version 0.0.0-latest

helm template eg-crds oci://registry-1.docker.io/envoyproxy/gateway-crds-helm \
  --version 0.0.0-latest \
  --set crds.gatewayAPI.enabled=true \
  --set crds.gatewayAPI.channel=standard \
  --set crds.envoyGateway.enabled=true \
  | kubectl apply --server-side --force-conflicts -f -

tip

Helm pipes CRDs through kubectl apply because large CRD manifests can exceed Helm's template limits. See the upstream CRD install note.

Option B — GKE with provider-managed Gateway API CRDs

If GKE already installed compatible Gateway API Standard Channel CRDs, install Envoy Gateway CRDs only:

# Confirm provider bundle (optional)
kubectl get crd gateways.gateway.networking.k8s.io \
  -o go-template='version={{ index .metadata.annotations "gateway.networking.k8s.io/bundle-version" }} channel={{ index .metadata.annotations "gateway.networking.k8s.io/channel" }}{{ "\n" }}'

helm template eg-crds oci://registry-1.docker.io/envoyproxy/gateway-crds-helm \
  --version 0.0.0-latest \
  --set crds.gatewayAPI.enabled=false \
  --set crds.envoyGateway.enabled=true \
  | kubectl apply --server-side --force-conflicts -f -

When using provider-managed Gateway API CRDs, disable the safe-upgrade policy on the controller install (Step 2):

--set crds.gatewayAPI.safeUpgradePolicy.enabled=false

Verify CRDs

kubectl get crd | grep -E 'gateway\.networking|envoyproxy'
kubectl get crd gateways.gateway.networking.k8s.io
kubectl get crd envoyproxies.gateway.envoyproxy.io

CRDs are once per cluster. Re-run only when upgrading Envoy Gateway / Gateway API versions.

Step 2 — Install Envoy Gateway controller

Install the upstream controller per Envoy Gateway — Install with Helm. Chart tags: envoyproxy/gateway-helm on Docker Hub.

helm pull oci://registry-1.docker.io/envoyproxy/gateway-helm --version 0.0.0-latest

helm upgrade --install eg oci://registry-1.docker.io/envoyproxy/gateway-helm \
  --version 0.0.0-latest \
  -n envoy-gateway-system \
  --create-namespace \
  --skip-crds

For GKE + provider-managed Gateway API CRDs, add:

  --set crds.gatewayAPI.safeUpgradePolicy.enabled=false

Wait until the controller is ready:

kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway \
  --for=condition=Available

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

The controller Deployment reconciles Gateway, EnvoyProxy, and HTTPRoute objects. It does not create the platform Gateway resource — that is Step 3.

Step 3 — Install platform edge (`bh-gateway`)

Install the platform edge from the bh-gateway OCI chart. Full install steps, values, and verification: bh-gateway.

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

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

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

Confirm the Gateway is Programmed and the data-plane LoadBalancer has an EXTERNAL-IP before Step 4. Mirror charts to your GAR first: Release Manifest & Distribution.

Step 4 — HTTPRoutes (BigHammer chart)

HTTPRoutes are not installed by Steps 1–3. They ship with the bighammer chart when Gateway mode is enabled:

global:
  ingress:
    enabled: false
  gateway:
    enabled: true
    parentRef:
      name: bh-gateway
      namespace: envoy-gateway-system
      sectionName: https
    routes:
      bhui:
        hostname: ui.<env>.<your-domain>
        # ...

Deploy apps and routes via Platform Deployment after the edge stack above is healthy.

Change type	Edit	Re-install
Hostname / path / backend	`values-<env>.yaml` → `global.gateway.routes.*`	`helm upgrade bighammer` only
TLS listener / LB / ReferenceGrants	`bh-gateway/values-gcp.yaml`	`helm upgrade bh-gateway -n envoy-gateway-system`
New HTTPRoute namespace	`referenceGrants.routeNamespaces`	`helm upgrade bh-gateway -n envoy-gateway-system`

Route-only changes do not require CRD or controller reinstall.

GKE load balancer health

Summary: data-plane Service uses externalTrafficPolicy: Cluster and health checks on TCP 10256. Use cloud.google.com/l4-rbs and network-tier: Standard in bh-gateway values.

Full explanation, Service naming, and firewall guidance: bh-gateway — GKE load balancer.

End-to-end verification

# Controller
kubectl get pods -n envoy-gateway-system

# Platform edge
kubectl get gateway bh-gateway -n envoy-gateway-system
kubectl get svc -n envoy-gateway-system -o wide

# Routes (after bighammer deploy)
kubectl get httproute -n bh-control-plane

# Smoke test (replace hostname)
curl -kI https://ui.<env>.<your-domain>

Quick reference

Goal	Command
CRDs only	Step 1
Controller only	Step 2 (requires Step 1)
Platform Gateway + EnvoyProxy	bh-gateway (requires Steps 1–2)
App HTTPRoutes	Platform Deployment with `global.gateway.enabled: true`
Switch back to nginx	NGINX Ingress Deployment

Resource	Link
Envoy Gateway Helm install	gateway.envoyproxy.io — Install with Helm
bh-gateway install, values, LB, verify	bh-gateway
Mirror charts to GAR	Release Manifest & Distribution
TLS on Gateway listener	TLS Options
Deploy issues	Troubleshooting

Envoy Gateway (upstream)

CRD installation, controller Helm chart, version compatibility, and provider-managed Gateway API notes are documented by the Envoy Gateway project:

Install with Helm — gateway.envoyproxy.io

When to use Gateway API​

Architecture — who owns what​

Prerequisites​

Step 1 — Install CRDs​

Option A — Standard channel (recommended for new clusters)​

Option B — GKE with provider-managed Gateway API CRDs​

Verify CRDs​

Step 2 — Install Envoy Gateway controller​

Step 3 — Install platform edge (bh-gateway)​

Step 4 — HTTPRoutes (BigHammer chart)​

GKE load balancer health​

End-to-end verification​

Quick reference​

Further reading​

Envoy Gateway (upstream)​