Core Concepts: GatewayClass, Gateway, and HTTPRoute

Understanding the core resources is essential to working with Gateway API. This guide explains each resource and compares them to their Nginx Ingress equivalents.

Prerequisites

Before working with Gateway API resources, you need:

1. Gateway API CRDs Installed - Gateway API resources are not part of standard Kubernetes. You must install the Custom Resource Definitions (CRDs) first:

   kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.2.1" | kubectl apply -f -
   

   Copy

2. Gateway API Implementation - A Gateway API implementation (like NGINX Gateway Fabric) must be installed in your cluster:

   helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway
   

   Copy

   For detailed setup instructions, see the NGINX Gateway Fabric installation guide in the NGINX Gateway Fabric Documentation.

3. Verify Installation:

   kubectl get crd | Select-String gateway
   kubectl get gatewayclass
   

   Copy

   You should see Gateway API CRDs and at least one GatewayClass.

Overview: The Three Pillars

Gateway API has three main resources that work together:

1. GatewayClass - Defines the type of Gateway (like IngressClass)
2. Gateway - Defines network endpoints (like Ingress Controller setup)
3. HTTPRoute - Defines routing rules (like Ingress resource)

1. GatewayClass

What is GatewayClass?

GatewayClass defines a class of Gateways that share the same configuration and behavior. It's similar to IngressClass in the Ingress world.

Comparison: IngressClass vs GatewayClass

Nginx Ingress - IngressClass:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
spec:
  controller: k8s.io/ingress-nginx

Gateway API - GatewayClass:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx-gateway
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller

Key Differences

GatewayClass Example

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx-gateway
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller
  description: "Nginx Gateway API implementation"

NGINX Gateway Fabric Specific Notes:

• Single GatewayClass per Controller: NGF only actively uses one GatewayClass per controller instance. The controller is configured via the --gatewayclass flag and will only reconcile Gateways that belong to that specific class (typically named "nginx" by default). While the Gateway API specification allows multiple GatewayClasses, NGF's controller is typically deployed to handle one class. To use multiple GatewayClasses, you would need to run separate NGF controller instances, each configured for a different GatewayClass.

• Controller Name: The correct controllerName for NGINX Gateway Fabric is gateway.nginx.org/nginx-gateway-controller (this is the default when using the official Helm chart). Using an incorrect controller name will result in the GatewayClass not being accepted by NGF. When properly configured, the GatewayClass status will show Accepted: True.

• Parameters Reference: NGF supports an optional parametersRef on GatewayClass that references an NginxProxy resource for custom NGF settings. This allows you to pass implementation-specific configuration to the data plane:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx-gateway
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller
  parametersRef:
    group: gateway.nginx.org
    kind: NginxProxy
    name: nginx-proxy-config
    namespace: nginx-gateway

Who manages it? Cluster administrators

2. Gateway

What is Gateway?

Gateway defines network endpoints (listeners) that receive traffic. It's similar to setting up an Ingress Controller, but defined as a Kubernetes resource.

Comparison: Ingress Controller Setup vs Gateway

Nginx Ingress - Controller Setup:

• Deployed as a Deployment/DaemonSet
• Configured via ConfigMap
• Listens on ports 80/443
• Managed outside of Kubernetes resources

Gateway API - Gateway Resource:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: nginx-gateway
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All

Key Differences

Gateway Components

Listeners

Listeners define what ports and protocols the Gateway accepts:

listeners:
  - name: http
    protocol: HTTP
    port: 80
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
        - name: my-cert

NGINX Gateway Fabric Limitations:

• Protocol Support: NGF only supports HTTP and HTTPS protocols. Protocols like TCP, UDP, or generic TLS (passthrough) are not supported. NGF focuses on Layer 7 (HTTP/HTTPS) routing.
• TLS Certificates: NGF supports at most one TLS certificate reference per listener. If multiple certificates are specified, only the first will be used.
• TLS Mode: Only Terminate mode is supported. TLS passthrough is not supported in NGF.

Allowed Routes

Controls which HTTPRoutes can attach to this Gateway:

allowedRoutes:
  namespaces:
    from: All  # or Same, or Selector

Gateway Addresses

Gateway addresses define how external traffic reaches the Gateway. In NGINX Gateway Fabric:

• Dynamic Address Allocation: NGF does not support automatic address allocation when spec.addresses is left empty. You should explicitly specify addresses in the Gateway spec, or the Gateway will use the Service IP from the NGINX data plane (which may be a LoadBalancer or NodePort Service depending on your cluster configuration).
• Multiple Gateways: NGF supports deploying multiple Gateway resources concurrently, each with its own independent NGINX data plane deployment. This allows different teams or applications to have isolated Gateways.

Who manages it? Infrastructure/Operations teams

3. HTTPRoute

What is HTTPRoute?

HTTPRoute defines routing rules for HTTP/HTTPS traffic. It's the direct replacement for the Ingress resource.

Comparison: Ingress vs HTTPRoute

Nginx Ingress - Ingress Resource:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: my-service
                port:
                  number: 80

Gateway API - HTTPRoute:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: my-service
          port: 80

Key Differences

HTTPRoute Structure

Parent References

HTTPRoutes must reference which Gateway(s) they attach to:

parentRefs:
  - name: my-gateway
    namespace: default

Hostnames

Define which hostnames this route handles:

hostnames:
  - example.com
  - www.example.com

Rules

Rules contain matches and actions:

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api
    backendRefs:
      - name: my-service
        port: 80

Cross-Namespace Routing and ReferenceGrant

Gateway API supports cross-namespace routing, but requires explicit authorization for security:

• Cross-Namespace Gateway Attachment: If an HTTPRoute is in a different namespace than the Gateway, the Gateway's allowedRoutes configuration must permit it (e.g., from: All or using a namespace selector).

• Cross-Namespace Backend References: If an HTTPRoute's backendRefs point to a Service in another namespace, a ReferenceGrant resource is required in the target namespace to authorize the reference.

Example: HTTPRoute referencing a cross-namespace Service

# HTTPRoute in namespace "app"
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-route
  namespace: app
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: backend-service
          namespace: backend  # Different namespace!
          port: 80

ReferenceGrant in the target namespace (required):

# ReferenceGrant in namespace "backend"
apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-app-namespace
  namespace: backend
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: app
  to:
    - group: ""
      kind: Service

NGINX Gateway Fabric Note: NGF fully enforces this security model. An HTTPRoute cannot send traffic to a cross-namespace Service without an appropriate ReferenceGrant. NGF supports the ReferenceGrant resource for this purpose.

NGINX Gateway Fabric Limitations:

• Filter Limitations: NGF supports only one filter of a given type per route rule. If multiple filters of the same type are listed in a single rule, NGF will apply only the first and ignore subsequent filters. The exception is RequestMirror filters - multiple RequestMirror filters are allowed in a single rule.

• Extended Fields Not Supported: NGF does not yet support some extended fields in HTTPRoute rules such as timeouts, retries, or sessionPersistence. If these fields are defined in an HTTPRoute, NGF will ignore them. NGF focuses on core routing features and defers advanced traffic policies to future releases.

Who manages it? Application developers

4. BackendRef

What is BackendRef?

BackendRef is how HTTPRoute references backend services. It's more powerful than Ingress backends.

Comparison: Ingress Backend vs BackendRef

Nginx Ingress - Backend:

backend:
  service:
    name: my-service
    port:
      number: 80

Gateway API - BackendRef:

backendRefs:
  - name: my-service
    port: 80
    weight: 100

Advanced BackendRef Features

Weighted Routing

backendRefs:
  - name: stable-service
    port: 80
    weight: 90
  - name: canary-service
    port: 80
    weight: 10

This is native in Gateway API, but requires annotations in Nginx Ingress!

Role-Oriented Model

One of Gateway API's key innovations is the role-oriented model:

Infrastructure Team (Gateway)

• Manages GatewayClass and Gateway resources
• Controls ports, protocols, TLS certificates
• Sets namespace access policies
• Handles infrastructure concerns

Application Team (HTTPRoute)

• Manages HTTPRoute resources
• Defines routing rules, hostnames, paths
• References backend services
• Handles application concerns

Benefits

1. Clear Separation: Infrastructure and app teams don't step on each other
2. RBAC: Different permissions for different roles
3. Scalability: App teams can create routes without touching infrastructure
4. Portability: Routes work with any Gateway

Complete Example: Side-by-Side

Nginx Ingress Setup

Step 1: IngressClass

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
spec:
  controller: k8s.io/ingress-nginx

Step 2: Ingress Resource

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: app-service
                port:
                  number: 80

Gateway API Setup

Step 1: GatewayClass

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx-gateway
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller

Step 2: Gateway

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

Step 3: HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: app-service
          port: 80

Summary

Next Steps

Now that you understand the core concepts, let's learn about basic routing:

👉 Next: Basic Routing →

Related Examples

• gatewayclass.yaml - GatewayClass example
• gateway.yaml - Gateway example
• httproute-basic.yaml - Basic HTTPRoute
• ingress-equivalent.yaml - Nginx Ingress equivalent