Services and ingress

Why you can’t address a pod directly

When you deploy to Kubernetes, the first instinct is to grab the pod’s IP and call it directly — and that instinct is exactly what gets you into the failure in the hook above. Here is why it can never work reliably.

A pod is the cheapest, most disposable thing in Kubernetes. The scheduler kills it, reschedules it, scales it up and down, and moves it to another node on a whim — and every time it comes back it gets a new IP from the pod network. There is no stable address you can hardcode, no DNS name that survives a rollout, no guarantee the IP you resolved a second ago still belongs to a live pod. Directly dialing a pod IP is a bug waiting for the next reschedule.

The Service is the fix. It is an API object that gives a set of pods one stable identity: a virtual IP (the ClusterIP) and a DNS name (<service>.<namespace>.svc.cluster.local) that live for the lifetime of the Service, independent of which pods exist behind it right now. Clients talk to the Service; the Service load-balances each connection across the healthy pods. Pods churn underneath; the address in front never moves.

The selector-to-endpoints mechanism

The link between a Service and its pods is labels, not IPs. A Service declares a selector — a set of label key/values — and Kubernetes continuously watches for pods that (a) match every label in the selector and (b) are Ready (passing their readiness probe). For each such pod it records the pod IP and port into an EndpointSlice (the modern, sharded replacement for the older single Endpoints object). That EndpointSlice is the load-balancing target list; kube-proxy on every node programs the data plane (iptables or IPVS rules) from it.

apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api            # must match the pods' labels exactly
  ports:
    - name: http
      port: 80          # the Service's virtual port
      targetPort: 8080  # the container port on the pod

Two things follow from this. First, the matching is dynamic: scale the Deployment up and new Ready pods are added to the slice within moments; a pod that fails its readiness probe is removed, so traffic stops going to it without you deleting anything. Second — and this is the failure that bites everyone — if the selector matches no Ready pods, the EndpointSlice is empty, and the Service routes to nowhere. It still has a ClusterIP, still resolves in DNS, still accepts connections — and then refuses or times out, because there is no backend to forward to.

Service types: how far the address reaches

Every Service has a type that decides who can reach it. They stack: each builds on the one before.

Together these types form a single decision: how far outside the cluster do you need the traffic to reach? Start with ClusterIP for everything internal; reach for Ingress (not LoadBalancer) the moment you need HTTP routing to the public internet.

ClusterIP is the default and the workhorse — it is how your API talks to your database talks to your cache, all by DNS name, all internal. NodePort opens the same port on every node and forwards it to the Service; it is the crude knob for getting traffic in, useful in dev or when you front it with your own load balancer, but you would not hand a raw node-ip:31000 URL to users. LoadBalancer asks the cloud provider to provision a real external load balancer pointing at the Service — clean, but you pay for and manage one LB per Service, which gets expensive and unwieldy fast. Headless opts out of the virtual IP entirely: DNS returns the individual pod IPs, which is exactly what a StatefulSet (database, broker) needs so clients can address a specific replica.

Ingress: one front door for many Services

If LoadBalancer gives you one cloud LB per Service, ten public services cost ten load balancers — and you still have no HTTP-aware routing. Ingress solves both. It is an L7 (HTTP/HTTPS) router that sits in front of your ClusterIP Services and dispatches requests by host and path to the right Service, terminates TLS centrally, and does it all behind a single shared load balancer. One entry point, many backends, far cheaper than an LB per service.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: site
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api      # routes /api -> the api Service
                port:
                  number: 80
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web      # routes everything else -> the web Service
                port:
                  number: 80

The crucial catch: the Ingress object is just rules. It does nothing on its own. You must run an ingress controller — nginx, Traefik, HAProxy, a cloud provider’s — which actually watches Ingress objects and turns them into a running reverse proxy. No controller, no routing; the YAML applies cleanly and traffic still goes nowhere. The ingressClassName tells Kubernetes which controller owns this Ingress.

The classic failure: zero endpoints

Return to the hook. The number-one Kubernetes networking bug is a Service whose selector does not match its pods’ labels. Nothing errors at apply time — the Service is valid YAML, gets a ClusterIP, resolves in DNS. But its selector matches no Ready pods, so the EndpointSlice is empty, and every connection is refused or times out. The same empty-endpoints symptom also comes from pods that match the labels but are not Ready (a failing or too-strict readiness probe), or a targetPort that doesn’t match the container’s actual port.

The diagnosis is always the same one command: kubectl get endpoints <svc> (or kubectl get endpointslices). If it shows <none> or no addresses, the Service is talking to no one — stop debugging the app and go check that the Service’s selector exactly equals the pods’ labels and that the pods are Ready.