Kubernetes Ingress and Gateway Routing

Kubernetes Ingress and Gateway Routing are the layer 7 traffic management mechanisms that expose HTTP and HTTPS workloads running inside a cluster to clients, routing incoming requests to the correct backend Service based on hostnames, paths, and other request attributes, and optionally handling concerns such as TLS termination. Where a Service operates primarily at the transport layer, Ingress and its successor, the Gateway API, express intent at the application layer, closer to how a reverse proxy or API gateway is typically configured.

Ingress

The Ingress Resource

An Ingress object declares a set of routing rules: a host, a set of path matchers, and the backend Service each matching request should be forwarded to. It is a declarative description of desired routing behavior, not an implementation; by itself, an Ingress resource has no effect unless a controller is present to act on it.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: codartium-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - host: app.codartium.example
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: codartium-api
                port:
                  number: 80
          - path: /
            pathType: Prefix
            backend:
              service:
                name: codartium-frontend
                port:
                  number: 80

Ingress Controllers

An Ingress controller is a component, typically running as a Deployment inside the cluster, that watches Ingress resources and configures an underlying proxy, such as NGINX, HAProxy, Envoy, or a cloud provider's load balancer, to implement the described routing. Because Kubernetes does not ship a default Ingress controller, one must be installed explicitly, and different controllers support different sets of annotations and behaviors beyond the common Ingress specification.

TLS Termination

An Ingress can specify TLS configuration, referencing a Secret containing a certificate and private key, allowing the Ingress controller to terminate HTTPS connections at the cluster edge and forward decrypted traffic to backend Services over plain HTTP internally.

spec:
  tls:
    - hosts:
        - app.codartium.example
      secretName: codartium-tls-cert

Limitations of Ingress

The Ingress API was intentionally minimal, covering only the most common routing needs, which led to divergent, controller-specific annotations for anything beyond basic host and path matching, such as traffic splitting, header-based routing, or protocol support beyond HTTP, reducing portability between different Ingress controller implementations.

Gateway API

Motivation

The Gateway API was developed as a more expressive, portable successor to Ingress, addressing its limitations by defining a richer, role-oriented set of resources with a standardized way to express advanced routing behavior without resorting to vendor-specific annotations.

Core Resources

• GatewayClass: Defines a class of gateway implementation, analogous to how a StorageClass defines a class of storage provisioner, typically managed by infrastructure operators.
• Gateway: Represents an actual listener configuration, binding to specific ports, protocols, and hostnames, typically managed by cluster or platform operators.
• HTTPRoute (and protocol-specific equivalents such as TCPRoute, GRPCRoute): Defines routing rules attached to a Gateway, typically managed by application teams, specifying how matching requests should be routed, modified, or split across backends.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: codartium-gateway
spec:
  gatewayClassName: codartium-gateway-class
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        certificateRefs:
          - name: codartium-tls-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: codartium-api-route
spec:
  parentRefs:
    - name: codartium-gateway
  hostnames:
    - "app.codartium.example"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: codartium-api
          port: 80

Role Separation

Gateway API's separation of GatewayClass, Gateway, and Route resources reflects a deliberate division of responsibility: infrastructure teams manage shared listener and TLS configuration through Gateway resources, while application teams manage their own routing rules through Route resources, without needing broad permissions over shared infrastructure objects.

Choosing Between Ingress and Gateway API

Compatibility Considerations

Ingress remains widely supported and sufficient for straightforward host- and path-based routing to a small number of backend Services, and benefits from broad tooling maturity built up over years of use. Gateway API is designed for more complex routing needs, traffic splitting for canary releases, protocol support beyond HTTP, and clearer multi-team ownership boundaries, at the cost of requiring a compatible controller implementation.

kubectl get ingressclass
kubectl get gatewayclass
kubectl describe httproute codartium-api-route

Coexistence

Because Gateway API was designed to be adopted incrementally, clusters commonly run both Ingress and Gateway API resources side by side during a migration period, with new routing configuration expressed through Gateway API resources while legacy Ingress objects continue to function unchanged.