Skip to content

Gateway API Migration (ingress-nginx → nginx Gateway Fabric)

Operational guide for the MeshFlows edge migration from ingress-nginx to nginx Gateway Fabric with cert-manager Gateway API support.

Internal design notes: internal/k8s-gateway-api-migration.md.

Status

Manifests and infra.yml target Gateway API resources. New clusters should install nginx Gateway Fabric directly. Existing clusters with ingress-nginx should migrate using the rollout order below, then remove ingress-nginx.

What Changed

Area Before After
Edge routing Ingress resources Gateway + HTTPRoute
TLS ingress annotations Gateway TLS + cert-manager Gateway API solver
Infra workflow nginx-ingress component nginx-gateway-fabric component
cert-manager ingress.ingressClassName solver gatewayHTTPRoute + solver Gateway parentRef

Key manifest locations:

  • engine/deploy/k8s/ — base Gateway + HTTPRoutes (patched per environment)
  • engine/deploy/overlays/linux-cluster/infra/ — hostname patches, edge-router
  • wiki/deploy/k8s/ — wiki Gateway + HTTPRoute
  • .github/workflows/infra.yml — automated install

Rollout Order

Order matters. Do not apply app Gateway manifests before infrastructure is ready.

Run infra.yml with components=all, then deploy apps via deploy.yml.

Option B — Manual

# 1. Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml

# 2. nginx Gateway Fabric
helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
helm upgrade --install ngf nginx-stable/nginx-gateway-fabric \
  --namespace nginx-gateway --create-namespace \
  --version 2.4.2 --set service.type=NodePort --wait
# Use chart 2.5.1+ on Kubernetes 1.31+

# 3. GatewayClass
kubectl apply -f - <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller
EOF

# 4. cert-manager with Gateway API
helm upgrade cert-manager jetstack/cert-manager \
  --namespace cert-manager --version v1.17.2 \
  --set crds.enabled=true --set config.enableGatewayAPI=true --wait

# 5. Solver Gateway + ClusterIssuers — see infra.yml steps

# 6. Application manifests
kubectl apply -k engine/deploy/overlays/linux-cluster/

Remove old ingress-nginx (after verification)

helm uninstall ingress-nginx -n ingress-nginx
kubectl delete namespace ingress-nginx

Hostnames per Environment

Base manifests use placeholders. Overlays patch Gateway listeners, for example:

spec:
  listeners:
    - name: https
      hostname: lab-gateway.meshflows.org
      tls:
        certificateRefs:
          - name: meshflows-tls

See Lab HTTPS Setup for DNS and Fritzbox configuration.

Verification

kubectl get gateway -A
kubectl describe gateway meshflows -n meshflows-lab
kubectl get httproute -A
kubectl get certificate -A

curl -k -H "Host: lab-gateway.meshflows.org" https://<node-ip>:30443/