Kubernetes Gateway API: Resources, GatewayClass, and the Right Defaults

Kubernetes Gateway API is the official successor to Ingress, per the K8s docs. Three resources: GatewayClass (infra provider), Gateway (L4/L7 listener with associated LB), HTTPRoute (path/header matching). The team that uses Gateway API for new deployments has the modern approach. The team that stays on Ingress for now has stability + existing tooling.

Why Gateway API
The three core resources
GatewayClass example
Gateway example
HTTPRoute example
Implementations
Migrating from Ingress
FAQ

Why Gateway API

Ingress limitations:

Annotation-heavy (different per controller).
Single spec, limited expressiveness.
No TCP/UDP support (only HTTP/HTTPS).

Gateway API improvements:

Standardized, role-oriented resources.
Multi-protocol (HTTP, TCP, UDP, TLS).
Expressive routing (path, header, query, method).
Cloud-native with multiple implementations.

The three core resources

GatewayClass: defines the infra provider (nginx, envoy, cilium, AWS LB Controller).
Gateway: a listener (port + protocol + TLS) bound to a GatewayClass.
HTTPRoute (or TCPRoute, UDPRoute, TLSRoute): routing rules bound to a Gateway.

The team that uses these has clean separation between infra (GatewayClass), listeners (Gateway), and routing (HTTPRoute).

GatewayClass example

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

The controllerName matches the implementation (NGINX Gateway, Envoy Gateway, Cilium, etc.). The team that has multiple GatewayClasses has different routing engines for different needs.

Gateway example

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: nginx
  listeners:
    - name: http
      port: 80
      protocol: HTTP
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: my-tls-secret
            kind: Secret

The team that uses Gateway with HTTPS termination has TLS handled at the gateway.

HTTPRoute example

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: my-app
          port: 8080

The team that uses HTTPRoute has clean host/path routing.

Implementations

NGINX Gateway (nginx-gateway-fabric): from the NGINX team.
Envoy Gateway (gateway.envoyproxy.io): CNCF, Envoy-based.
Cilium Gateway: Cilium’s eBPF-based implementation.
Istio: supports Gateway API as of 1.21.
AWS Load Balancer Controller: creates ALB/NLB for Gateway.
Google Cloud Gateway Controller: GCP-native.

The team that picks based on existing tooling has the right implementation.

Migrating from Ingress

The team that has existing Ingress:

Deploy Gateway API alongside Ingress (no conflict).
Create GatewayClass + Gateway.
Add HTTPRoutes for new services.
Migrate Ingress rules one by one.
Remove Ingress after all migrated.

The team that does a big-bang migration has more risk. The team that migrates incrementally has lower risk.

FAQ

Is Gateway API stable?

Yes - graduated to GA in K8s 1.24 (2023). Most implementations have reached v1.0. The team that uses it on new deployments has production-ready tooling.

Should I migrate from Ingress?

For new projects, yes. For existing projects with stable Ingress, plan migration but don’t rush. The team that has time migrates incrementally.

What’s the difference between Gateway API and Ingress?

Ingress: one spec, HTTP-only, annotation-heavy. Gateway API: multiple role-oriented resources, multi-protocol, expressive. Gateway API is the future.

Do all ingress controllers support Gateway API?

Most do - NGINX, Envoy, Cilium, Istio, Traefik. Some older controllers (nginx-ingress) are still Ingress-only. The team that picks a modern controller has Gateway API support.

Can I use Gateway API and Ingress at the same time?

Yes - they coexist. The team that has both during migration has a clean transition path.

If you are sizing the infrastructure for the kind of project this post covers, the RunxBuild hosting calculator is the right place to model the line items. The compute, the memory, the storage, the bandwidth, the database - each one is a separate number, and the team’s mental model for the platform is the sum of those numbers. The RunxBuild dashboard is where the team sees the actual usage in one place.

Useful related references: