Introduction

Welcome to this lesson on the Gateway API with NGINX Fabric Gateway. I’m Pedro Ignácio, and I’ll guide you through deploying and operating an NGINX Fabric Gateway as a Gateway API data plane for Kubernetes. In modern cloud-native environments, controlling traffic into and within your clusters is essential. The traditional Ingress API has served well, but the Gateway API provides a more expressive, secure, and extensible model for routing, traffic management, and multi-controller use-cases. This lesson explains the Gateway API fundamentals, the control-plane / data-plane persona model, and step-by-step deployment and validation of NGINX Fabric Gateway.

A slide-like screenshot titled "Gateway API" showing a "Control Plane" header with a Kubernetes cluster diagram and a light-blue box labeled "Namespace – nginx-gateway." In the bottom-right is a small circular video thumbnail of a person speaking.

This lesson assumes you have access to a Kubernetes cluster, and that kubectl and helm are installed and configured to target your cluster.

You will need sufficient cluster permissions to create CRDs, namespaces, and install Helm charts (typically cluster-admin or equivalent). If you’re on a shared cluster, coordinate with your cluster administrators.

What you’ll learn

Why Gateway API matters: differences from Ingress and the problems it solves.
Gateway API resource model: GatewayClass, Gateway, and Routes (HTTPRoute, TCPRoute, gRPCRoute), plus the control-plane vs data-plane persona model.
NGINX Fabric Gateway as a data plane: installation, configuration, and operational checks.
Advanced traffic management: cross-namespace routing, traffic splitting, header-based routing (A/B tests), request/response filters, and zero-downtime canaries.
TLS management and secure cross-namespace references using ReferenceGrant.
Troubleshooting: interpreting status fields and debugging common errors.
Hands-on labs and an assessment to validate your learning.

Core Gateway API resources (at-a-glance)

Resource Type	Purpose	Example
GatewayClass	Defines a controller implementation (data plane).	`GatewayClass` named `nginx-gateway-class`
Gateway	Represents a L4/L7 load balancer instance controlled by a controller.	`Gateway` referencing a `GatewayClass`
HTTPRoute / TCPRoute / gRPCRoute	Route traffic from Gateways to Kubernetes services.	`HTTPRoute` with host and path matching
ReferenceGrant	Grants controllers permission to reference resources across namespaces.	`ReferenceGrant` allowing secret access

Getting started — quick verification examples

Early checks commonly include looking for Route resources and active pods:

~/coding/kubernetes/nginx-fabric-gateway/kodekloud/lab-2-canary
$ kubectl get httproute
No resources found in default namespace.

$ kubectl get pods
NAME                                   READY   STATUS    RESTARTS   AGE
coffee-5b9c74f9d9-9nf2f                1/1     Running   0          138m
gateway-nginx-5f9d4c4ff-2d7zp         1/1     Running   0          136m

Install Gateway API CRDs (from the NGINX Gateway Fabric repo)

Apply the required CRDs for Gateway API extensions used by NGINX Fabric Gateway:

controlplane ~ ➜ kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api" | kubectl apply -f -
customresourcedefinition.apiextensions.k8s.io/backendtlspolicies.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created

controlplane ~ ➜ kubectl get crd | grep gateway
backendtlspolicies.gateway.networking.k8s.io   2026-05-13T05:57:38Z
gatewayclasses.gateway.networking.k8s.io       2026-05-13T05:57:38Z
gateways.gateway.networking.k8s.io             2026-05-13T05:57:38Z
grpcroutes.gateway.networking.k8s.io           2026-05-13T05:57:38Z
httproutes.gateway.networking.k8s.io           2026-05-13T05:57:39Z
referencegrants.gateway.networking.k8s.io      2026-05-13T05:57:39Z

Deploy NGINX Fabric Gateway with Helm

Example Helm install for NGINX Fabric Gateway using NodePort listeners for ports 80 and 443:

controlplane ~ » helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
  --create-namespace \
  -n nginx-gateway \
  --set nginx.service.type=NodePort \
  --set-json 'nginx.service.nodePorts'='[{"port":31437,"listenerPort":80},{"port":30478,"listenerPort":443}]'
Pulled: ghcr.io/nginx/charts/nginx-gateway-fabric:2.6.0
Digest: sha256:0e67134aa0a9d262f0b5215204b938a34bd40d8cb84f0d5aaa13f61bb0f7a4
NAME: ngf
LAST DEPLOYED: Wed May 13 05:57:58 2026
NAMESPACE: nginx-gateway
STATUS: deployed
REVISION: 1
TEST SUITE: None

Validate the NGINX Fabric Gateway deployment

Check pods and services in the nginx-gateway namespace. Pods may show 0/1 while images download or init jobs run; they should quickly converge to 1/1:

controlplane ~ » kubectl get pods -n nginx-gateway
NAME                                            READY   STATUS      RESTARTS   AGE
ngf-nginx-gateway-fabric-858b68c56b-bnvxx       0/1     Running     0          9s
ngf-nginx-gateway-fabric-cert-generator-n9spw   0/1     Completed   0          14s

# After a short wait:
controlplane ~ » kubectl get pods -n nginx-gateway
NAME                                            READY   STATUS    RESTARTS   AGE
ngf-nginx-gateway-fabric-858b68c56b-bnvxx       1/1     Running   0          39s

Confirm the gateway service exists:

controlplane ~ » kubectl get svc -n nginx-gateway
NAME                        TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
ngf-nginx-gateway-fabric    ClusterIP   172.20.62.84    <none>        443/TCP   42s

Hands-on labs and example workloads

The labs included with this lesson walk through deploying example services (coffee and tea) and configuring Gateway and HTTPRoute resources for routing, traffic splitting, and canary deployments.

controlplane ~ ➜ kubectl get deployments
NAME            READY   UP-TO-DATE   AVAILABLE   AGE
coffee          1/1     1            1           118s
tea             1/1     1            1           117s

controlplane ~ ➜ kubectl get svc
NAME            TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
coffee          ClusterIP   172.20.23.26     <none>        80/TCP     118s
kubernetes      ClusterIP   172.20.0.1       <none>        443/TCP    33m
tea             ClusterIP   172.20.86.69     <none>        80/TCP     117s

controlplane ~ ➜ kubectl get pods
NAME                             READY   STATUS    RESTARTS   AGE
coffee-654ddf664b-5fqn6          1/1     Running   0          118s
tea-75bc9f4b6d-zdm5d             1/1     Running   0          117s

TLS, ReferenceGrant, and cross-namespace security

You will configure TLS termination on the Gateway, enable HTTPS redirects, and use ReferenceGrant objects to authorize controlled cross-namespace references (for example, allowing a Gateway in namespace A to reference a secret in namespace B). This explicit grant model improves security and auditability.

Troubleshooting and best practices

Learn to read and interpret the status fields on Gateway API resources to diagnose issues.
Common failure modes include:
- Gateway controller not reconciling (check controller logs).
- Route selection mismatches (ensure gatewayRef and selectors match).
- Secret or ReferenceGrant misconfigurations for TLS (verify ReferenceGrant allows the specific resource kinds and namespaces).
Debugging tips:
- Use kubectl describe on Gateway, GatewayClass, and Routes to inspect conditions.
- Check controller pod logs for errors or rejected configurations.
- Use kubectl get events -A to spot API-level errors.

Assessment and next steps

The course concludes with an assessment to validate your knowledge and recommended next steps:
- Explore advanced features like Filters in Routes, BackendTLSPolicies, and policy integration.
- Read the Gateway API specification and NGINX Fabric Gateway documentation for advanced configuration patterns.

Links and references

Gateway API specification: https://gateway-api.sigs.k8s.io/
NGINX Gateway Fabric (charts & repo): https://github.com/nginx/nginx-gateway-fabric
Kubernetes documentation: https://kubernetes.io/docs/

Community and support

At KodeKloud, we foster a hands-on community for questions and learning. Share your configurations, ask for help, and collaborate on real-world Gateway API scenarios.

Introduction & Why Gateway API

Core Gateway API Resources

Advanced Traffic Management

TLS and Cross-Namespace Security

Troubleshooting and Best Practices

Watch Video