Services, Ingress and the Gateway API

Why Services exist

Your frontend needs to call payments-api. But payments-api is 4 pods whose IPs change every time a pod is replaced. A Service is a stable front for a group of pods: it gets a fixed virtual IP address and a DNS name, and it load-balances requests across the matching pods that are ready.

apiVersion: v1
kind: Service
metadata:
  name: payments-api
  namespace: payments
spec:
  type: ClusterIP            # the default; can be left out
  selector:
    app: payments-api        # send traffic to pods with this label
  ports:
    - port: 80               # the port clients call on the Service
      targetPort: 8080       # the port the container listens on

The selector is the link. Kubernetes keeps a list of the IPs of pods that match the selector and pass their readiness probe. These lists are stored in EndpointSlice objects (the older Endpoints object did the same job). If the list is empty, the Service has nowhere to send traffic.

Service types

DNS names

The cluster DNS server (usually CoreDNS) gives every Service a name of the form <service>.<namespace>.svc.cluster.local, where cluster.local is the default cluster domain. Pods in the same namespace can simply call http://payments-api. From another namespace, use payments-api.payments, or the full name payments-api.payments.svc.cluster.local.

Ingress: one entrance for many services

Giving every service its own cloud load balancer is costly. Ingress is an object that describes HTTP and HTTPS routing rules: requests for shop.example.com/api go to the api Service, everything else to the web Service. One load balancer, many services.

An Ingress object is only a set of rules. Something must read those rules and route the traffic: an ingress controller, which you install in the cluster (for example a controller from your cloud provider, Traefik, HAProxy or an NGINX-based one). Without a controller, an Ingress does nothing at all.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  ingressClassName: example-controller   # which controller should handle this
  tls:
    - hosts: [shop.example.com]
      secretName: shop-tls                 # a Secret holding the certificate and key
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api
                port:
                  number: 80
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

How paths are matched

• Exact: the request path must be exactly the same, so /api matches only /api.
• Prefix: matches by path parts split on /. /api matches /api, /api/ and /api/orders, but NOT /apix.
• When several rules match, the longest path wins. If two are equally long, Exact beats Prefix.

The Gateway API: the newer way

The Gateway API is the newer, more expressive successor to Ingress. It splits the job into roles: a GatewayClass (which implementation), a Gateway (the entry point, owned by the platform team) and routes such as HTTPRoute (owned by app teams). It supports things Ingress needed vendor-specific annotations for, like header matching and splitting traffic by weight between two versions.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-api
  namespace: shop
spec:
  parentRefs:
    - name: public-gateway
  hostnames: ["shop.example.com"]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api
          port: 80
          weight: 90
        - name: api-v2
          port: 80
          weight: 10

Ingress is still supported, but it is frozen: it gets no new features. The widely used community ingress-nginx controller has been retired, so for a new cluster, check the current Kubernetes docs and your provider before choosing between an Ingress controller and a Gateway API implementation.