Chapter 27 of 47 · Services and discovery

Ingress and Gateway API: one front door

Exposing every Service as a LoadBalancer means one cloud load balancer, one IP and one TLS certificate per app. An Ingress puts a single smart front door in front of all of them: it reads the host name and path of each request and forwards it to the right Service. The Gateway API is its newer, more powerful successor.

Two parts: rules and a controller

Installing a controller

$ helm repo add traefik https://traefik.github.io/charts
$ helm install traefik traefik/traefik -n traefik --create-namespace
$ kubectl get svc -n traefik
NAME      TYPE           EXTERNAL-IP    PORT(S)
traefik   LoadBalancer   34.120.8.10    80:31080/TCP,443:31443/TCP

$ minikube addons enable ingress        # local, installs ingress-nginx

$ kubectl get ingressclass
NAME      CONTROLLER                      ACCEPTS
traefik   traefik.io/ingress-controller   default
nginx     k8s.io/ingress-nginx

Path-based routing

One host, different paths → different Services. Click the parts:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: blog
spec:
  ingressClassName: traefik
  rules:
    - host: blog.example.com
      http:
        paths:
          - path: /api/posts
            pathType: Prefix
            backend:
              service:
                name: posts-srv
                port:
                  number: 4000
          - path: /api/comments
            pathType: Prefix
            backend:
              service: { name: comments-srv, port: { number: 4001 } }
          - path: /
            pathType: Prefix
            backend:
              service: { name: client-srv, port: { number: 3000 } }

Your Node services receive the full path: posts sees /api/posts/42, so its routes must include the prefix. (Rewriting paths is controller-specific; see annotations below.)

Host-based routing

Different host names on the same front door, each with its own rules. Point all the DNS names at the controller's one IP:

  rules:
    - host: blog.example.com
      http: { paths: [ ... blog paths ... ] }
    - host: admin.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend: { service: { name: admin-srv, port: { number: 8080 } } }

# DNS (at your domain provider)
blog.example.com    A  34.120.8.10
admin.example.com   A  34.120.8.10      ← same IP, the Host header decides

Try the router

These are the rules from both examples combined, plus an Exact rule for /healthz. Type a URL or use the buttons:

TLS termination

"Terminating" TLS means the front door decrypts HTTPS, so your services only ever speak plain HTTP inside the cluster. One place holds the certificates; no app needs to handle them.

spec:
  tls:
    - hosts: [blog.example.com, admin.example.com]
      secretName: blog-tls          # type kubernetes.io/tls, holds tls.crt + tls.key
  rules: ...

metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt

Annotations: the messy part

The Ingress API only covers hosts, paths and TLS. Anything else (rewrites, redirects, timeouts, rate limits, CORS) is done with controller-specific annotations:

# ingress-nginx
nginx.ingress.kubernetes.io/rewrite-target: /$2
nginx.ingress.kubernetes.io/proxy-body-size: 10m
# Traefik uses its own Middleware objects instead

So an Ingress that works on one controller can silently behave differently on another. This is the main reason the Gateway API exists.

Gateway API

The Gateway API (stable since 2023, gateway.networking.k8s.io/v1) splits the front door into roles and puts common features in the standard itself:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web
spec:
  gatewayClassName: traefik
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      tls:
        certificateRefs:
          - name: blog-tls

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: blog
spec:
  parentRefs:
    - name: web
  hostnames: [blog.example.com]
  rules:
    - matches:
        - path: { type: PathPrefix, value: /api/posts }
      backendRefs:
        - name: posts-srv
          port: 4000
    - matches:
        - path: { type: PathPrefix, value: / }
      backendRefs:
        - name: client-srv
          port: 3000

Advice: learn Ingress, because it is everywhere. For a new cluster, prefer the Gateway API.

Try it locally

$ minikube addons enable ingress
$ kubectl apply -f blog-ingress.yaml
$ kubectl get ingress
NAME   CLASS   HOSTS              ADDRESS        PORTS
blog   nginx   blog.example.com   192.168.49.2   80
# make the name point to your cluster, on your laptop only:
$ echo "$(minikube ip) blog.example.com" | sudo tee -a /etc/hosts
$ curl http://blog.example.com/api/posts

Recap

• An Ingress is a set of host and path rules; an ingress controller must be installed to run them.
• Path routing: Exact beats Prefix; the longest Prefix wins; Prefix matches whole segments.
• Host routing: many names, one IP; the Host header picks the rules.
• TLS is terminated at the controller using a kubernetes.io/tls Secret; cert-manager automates certificates.
• Extra features need controller-specific annotations; the Gateway API standardises them and is the future.