DEV Community

Arnob
Arnob

Posted on

Deploying the Gateway API with NGINX Gateway Fabric

Kubernetes Ingress is officially being deprecated, with the Gateway API emerging as its modular, scalable, and expressive successor. This documentation provides an overview of the Gateway API architecture and a step-by-step guide to implementing it using NGINX Gateway Fabric.

captionless image

Why Transition to Gateway API?

The Gateway API was created to address four major limitations of the traditional Ingress model:

  • Shared Resources: Ingress often relies on a single shared YAML file, leading to configuration conflicts and CI failures.
  • Lack of Role Separation: Ingress mixes infrastructure concerns (TLS, certificates) with application routing, causing friction between platform teams and developers.
  • Limited Routing: Advanced features like canary deployments, retries, and header-based routing are often missing or inconsistent across vendors.
  • Vendor Lock-in: Ingress relies heavily on vendor-specific annotations, making YAML files non-portable.

The Four-Layer Architecture

The Gateway API uses a clean, four-layer structure to separate responsibilities:

  1. GatewayClass: The “brain” that defines the implementation (e.g., NGINX, Traefik, Istio).
  2. Gateway: The entry point or “front door” of the cluster, defining ports, protocols, and listeners.
  3. Routes (HTTPRoute, gRPCRoute, etc.): These replace old Ingress rules, telling Kubernetes how to forward traffic based on hosts or paths.
  4. Backend Reference: The final destination for traffic, typically a standard Kubernetes Service.

Architecture 

Client
   │
   ▼
LoadBalancer / NodePort
   │
   ▼
NGINX Gateway Fabric
   │
   ▼
Gateway API Resources
   │
   ├── HTTPRoute
   ├── TCPRoute
   └── TLSRoute
   │
   ▼
Kubernetes Services
   │
   ▼
Pods
Enter fullscreen mode Exit fullscreen mode

Prerequisites

You need:

  • Kubernetes cluster
  • Helm installed
  • MetalLB or Cloud LoadBalancer
  • kubectl access

Install Gateway API CRDs

Install official Gateway API CRDs:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml
Enter fullscreen mode Exit fullscreen mode

Verify:

kubectl get crd | grep gateway
Enter fullscreen mode Exit fullscreen mode

Install NGINX Gateway Fabric

Add Helm repo:

helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
Enter fullscreen mode Exit fullscreen mode

Install NGINX Gateway Fabric:

Here are the values.yaml we are deploying the gateway api in NodePort. Because it is deployed in a local VM, if it cloud, then we use a Load Balancer

nginxGateway:
  name: nginx-gateway
nginx:
  service:
    type: NodePort
Enter fullscreen mode Exit fullscreen mode

Deploying Nginx Gateway Fabric using Helm

helm install ngf nginx-stable/nginx-gateway-fabric \
  -n nginx-gateway \
  --create-namespace \
 -f values.yaml
Enter fullscreen mode Exit fullscreen mode

Check pods:

kubectl get pods -n nginx-gateway
Enter fullscreen mode Exit fullscreen mode

Verify GatewayClass

Check available GatewayClass:

kubectl get gatewayclass
Enter fullscreen mode Exit fullscreen mode

You should see:

nginx
Enter fullscreen mode Exit fullscreen mode

Example:

NAME    CONTROLLER                                  ACCEPTED
nginx   gateway.nginx.org/nginx-gateway-controller  True
Enter fullscreen mode Exit fullscreen mode

Deploy the nginx app Application

Create deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx-app
  template:
    metadata:
      labels:
        app: nginx-app
    spec:
      containers:
      - name: nginx-app
        image: nginx:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-app
spec:
  selector:
    app: nginx-app
  ports:
  - port: 80
    targetPort: 80
Enter fullscreen mode Exit fullscreen mode

Apply:

kubectl apply -f nginx-app.yaml
Enter fullscreen mode Exit fullscreen mode

Create Gateway 

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nginx-gateway
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All
Enter fullscreen mode Exit fullscreen mode

Apply:

kubectl apply -f gateway.yaml
Enter fullscreen mode Exit fullscreen mode

Create HTTPRoute 

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: nginx-app-route
spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: nginx-app
      port: 80
Enter fullscreen mode Exit fullscreen mode

Apply:

kubectl apply -f httproute.yaml
Enter fullscreen mode Exit fullscreen mode

Get External IP

Check service:

kubectl get svc -n nginx-gateway
Enter fullscreen mode Exit fullscreen mode

Example:

NAME                             TYPE           EXTERNAL-IP
ngf-nginx-gateway-fabric         LoadBalancer   192.168.1.240
Enter fullscreen mode Exit fullscreen mode

Open browser:

http://192.168.1.240
Enter fullscreen mode Exit fullscreen mode

Production Example

HTTPS Gateway 

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nginx-gateway
spec:
  gatewayClassName: nginx
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    hostname: app.example.com
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: tls-secret
Enter fullscreen mode Exit fullscreen mode

Create TLS Secret 

kubectl create secret tls tls-secret \
  --cert=fullchain.pem \
  --key=privkey.pem
Enter fullscreen mode Exit fullscreen mode

Advanced Features

NGF supports:

  • Canary deployment
  • Traffic splitting
  • Rate limiting
  • Header modification
  • JWT auth
  • mTLS
  • TCP/UDP proxy
  • Multi Gateway
  • Cross namespace routing

Debugging

Check Gateway 

kubectl describe gateway nginx-gateway
Enter fullscreen mode Exit fullscreen mode

Check Route 

kubectl describe httproute nginx-app-route
Enter fullscreen mode Exit fullscreen mode

Check Logs 

kubectl logs -n nginx-gateway deploy/ngf-nginx-gateway-fabric
Enter fullscreen mode Exit fullscreen mode

Example Production Topology 

Internet
   │
Cloud LoadBalancer
   │
NGINX Gateway Fabric
   │
Gateway API
   │
├── frontend-route
├── api-route
├── auth-route
└── websocket-route
   │
Services
   │
Pods
Enter fullscreen mode Exit fullscreen mode

Advanced Features and Policies

The Gateway API introduces powerful built-in policies that do not require hacks or annotations:

  • Standalone Policies: BackendTLSPolicy (controls TLS behavior) and BackendTrafficPolicy (controls timeouts and retries).
  • Route-Level Filters: Supports traffic splitting (canary deployments), header manipulation, and request/response filters.

Why Gateway API over Ingress? 

| Feature                    | Ingress | Gateway API |
| -------------------------- | ------- | ----------- |
| TCP/UDP                    | Limited | Native      |
| Role separation            | Poor    | Excellent   |
| Traffic splitting          | Hard    | Native      |
| Multi listener             | Limited | Native      |
| Extensibility              | Medium  | High        |
| Future Kubernetes standard | No      | Yes         |
Enter fullscreen mode Exit fullscreen mode

Top comments (0)