Lesson 7 of 8 in Kubernetes

Ingress and Gateway API: routing from outside

Advanced13 min

Ingress and Gateway API are two ways to describe HTTP routing rules, such as sending one host name or path to one Service. Neither does anything alone. A controller in the cluster has to read the rules and run the actual proxy.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Services: stable addresses and DNS names for Pods, Networking for DevOps

The problem this solves

A ClusterIP Service is reachable only from inside the cluster. To put several web apps behind one address, with different hostnames and paths and with TLS, you need something that listens on the edge and routes requests. Creating one cloud load balancer per Service gets expensive and hard to manage.

Routing objects solve this. You write the rules as Kubernetes objects, and a controller turns them into the configuration of a real proxy or load balancer.

How it works

How an outside request reaches a Pod
How an outside request reaches a PodA client sends an HTTP request to a controller, the controller applies the routing rules you wrote, and it forwards to a Service, which reaches the Pods.1 HTTPrequest2 rules are read3 match hostand path4 forwardClientbrowser or curlControllerthe real proxyRouting rulesIngress or HTTPRouteServicePods
  • People and clients
  • Network
  • Control
  • Runs code

A client sends an HTTP request to a controller, the controller applies the routing rules you wrote, and it forwards to a Service, which reaches the Pods.

  1. Client to Controller: 1 HTTP request
  2. Routing rules to Controller: 2 rules are read
  3. Controller to Service: 3 match host and path
  4. Service to Pods: 4 forward
The Gateway API objects
The Gateway API objectsA GatewayClass names the controller, a Gateway opens listeners using it, and an HTTPRoute attaches to the Gateway and sends traffic to a Service.1 uses class2 attachesto3 sendstrafficGatewayClasswhich controllerGatewaylisteners and portsHTTPRoutehost, path, backendService
  • Control
  • Network

A GatewayClass names the controller, a Gateway opens listeners using it, and an HTTPRoute attaches to the Gateway and sends traffic to a Service.

  1. Gateway to GatewayClass: 1 uses class
  2. HTTPRoute to Gateway: 2 attaches to
  3. HTTPRoute to Service: 3 sends traffic

Follow the first diagram. The client contacts the controller, which listens on a public address. The rules, written as Ingress or HTTPRoute objects, live in the API server. The controller watches them and updates its own configuration. Then it picks a Service by host and path and forwards the request.

Ingress is the older API. It is stable, but it is frozen, and the Kubernetes project now recommends Gateway API for new work. The most widely used Ingress controller, ingress-nginx, was retired by the Kubernetes project: best-effort maintenance ran until March 2026, with no further releases or security fixes after that. Existing installs keep running, but you should not start a new one.

Gateway API splits the job by role. The platform team owns the GatewayClass and Gateway. App teams write an HTTPRoute for their own Service. Its objects are not built into Kubernetes, so you install its CRDs, which are extra resource types, and then a controller that supports it. Many controllers do, including Envoy-based and cloud ones, and the Gateway API site lists them.

Try it yourself

A bare kind cluster has no routing controller, which is the best way to see that the objects alone do nothing. Run these in a throwaway folder.

  1. 1
    Create a backend and an Ingress
    cat > ing.yaml <<'EOF'
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: web
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: web
      template:
        metadata:
          labels:
            app: web
        spec:
          containers:
            - name: nginx
              image: nginx:1.27
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: web
    spec:
      selector:
        app: web
      ports:
        - port: 80
    ---
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: web
    spec:
      rules:
        - host: web.example.test
          http:
            paths:
              - path: /
                pathType: Prefix
                backend:
                  service:
                    name: web
                    port:
                      number: 80
    EOF
    kubectl apply -f ing.yaml
    kubectl get ingress web

    The Ingress is accepted, but the ADDRESS column stays empty because no controller is reading it.

  2. 2
    Check whether Gateway API exists here
    kubectl api-resources | grep -i gateway

    On a fresh kind cluster this prints nothing. The Gateway API types are not part of core Kubernetes and must be installed.

  3. 3
    Read what an HTTPRoute looks like
    cat > route.yaml <<'EOF'
    apiVersion: gateway.networking.k8s.io/v1
    kind: HTTPRoute
    metadata:
      name: web
    spec:
      parentRefs:
        - name: my-gateway
      hostnames: ["web.example.test"]
      rules:
        - matches:
            - path:
                type: PathPrefix
                value: /
          backendRefs:
            - name: web
              port: 80
    EOF
    kubectl apply -f route.yaml

    This fails here, which is the lesson. See the first failure below. To use it for real, install the Gateway API CRDs and a controller from the project's install guide, and create a Gateway named my-gateway.

  4. 4
    Clean up
    kubectl delete -f ing.yaml
    rm ing.yaml route.yaml

What breaks, and where to look

  • error: no matches for kind "HTTPRoute" in version "gateway.networking.k8s.io/v1" - ensure CRDs are installed first.

    WHY IT HAPPENS
    The Gateway API custom resource definitions are not installed. They are separate from core Kubernetes.
    CHECK FIRST
    Run kubectl api-resources | grep -i gateway. If empty, install the CRDs and a Gateway API controller by following the official install instructions.
  • The Ingress exists, but kubectl get ingress shows no ADDRESS and requests go nowhere.

    WHY IT HAPPENS
    No Ingress controller is installed, or the Ingress names an ingressClassName that no installed controller handles. The object is only data until a controller acts on it.
    CHECK FIRST
    Run kubectl get ingressclass and kubectl get pods -A to find the controller. Run kubectl describe ingress <name> and check the class and the events.
  • You get an HTTP 404 from the proxy, not from your app.

    WHY IT HAPPENS
    The proxy is working but no rule matched. The Host header, the path or the pathType differs from your rule, or the Service has no ready endpoints.
    CHECK FIRST
    Send the exact host with curl -H 'Host: web.example.test' http://<controller-address>/, then run kubectl get endpointslices -l kubernetes.io/service-name=<service-name>.

When not to use this

  • For a first small app, kubectl port-forward is enough and needs no controller. Add routing when you have real external traffic.
  • Do not start a new setup on ingress-nginx. Choose a controller that is maintained, and prefer Gateway API where your controller supports it. The ingress2gateway tool can help migrate existing Ingress objects.

Check yourself

Why does an Ingress or HTTPRoute alone not route any traffic?

They are only rules. A controller must watch them and configure a real proxy or load balancer.

What is the status of ingress-nginx?

The Kubernetes project retired it, with best-effort maintenance ending in March 2026 and no later security fixes. Do not use it for new setups.

What does an HTTPRoute use to say which Gateway it belongs to?

parentRefs, which names the Gateway the route attaches to.

Lesson 76 of 92 in the DevOps path

Search

Search cheat sheets and projects