Service Types

## The three ports name three different endpoints When a client inside the cluster calls a Service, one packet gets rewritten once on its way to a pod. Each field names a different end of that rewrite. **`spec.ports[].port`** is the Service's own port: the port exposed on its virtual IP and, by extension, the port implied by its DNS name. `http://api.default.svc.cluster.local:80` uses `port: 80`. It is the only one of the three that clients care about. **`spec.ports[].targetPort`** is the destination port on the selected pods. The node dataplane rewrites the destination address to `<podIP>:<targetPort>`. If you omit `targetPort`, it defaults to the same numeric value as `port` - the source of the common belief that a Service has "one port". **`spec.ports[].nodePort`** exists only for `type: NodePort` and `type: LoadBalancer`. It is the port bound on every node so that outside traffic can enter. If you do not set it, Kubernetes allocates from the configured range (30000-32767 by default). Setting it by hand is allowed but invites collisions; the API server rejects a manifest whose pinned value is already taken. ## Named target ports `targetPort` accepts either an integer or a string. A string is looked up against the `name` field of a `containerPort` entry in each backing pod: Pod: `ports: [{name: http, containerPort: 8080}]`, Service: `targetPort: http`. The resulting endpoint is `podIP:8080`. Why bother? Because the mapping is resolved **per pod**. If you are migrating an app from 8080 to 9090, pods running the new image can declare `name: http, containerPort: 9090` while old pods still say 8080, and one unchanged Service routes correctly to both during the rollout. Port names are limited to 15 characters and must be IANA_SVC_NAME-shaped (lowercase alphanumeric and dashes, containing at least one letter). The catch: if a backing pod has no `containerPort` with that name, that pod produces no endpoint for the port. The Service then silently drops it from the pool, which looks like an intermittent "some requests fail" problem. ## containerPort is documentation, targetPort is not A frequent confusion: declaring `containerPort: 8080` in a pod spec does **not** open, publish or restrict anything. Container networking gives the pod a real IP, and any port the process binds is reachable from the cluster network regardless of what the manifest says. `containerPort` matters in exactly two places: as the target of a **named** `targetPort`, and as human/tooling documentation (some dashboards and `kubectl` heuristics read it). So a numeric `targetPort: 8080` works even if no `containerPort` is declared at all, as long as the process really listens on 8080. Conversely, declaring `containerPort: 8080` while the process listens on 3000 breaks nothing by itself, but any Service pointing at 8080 will fail to connect. ## Multiple ports `spec.ports` is a list, and once there is more than one entry each **must** have a `name` (single-port Services may omit it). Names also flow into the endpoint objects and are what tooling uses to disambiguate, e.g. a Service exposing `http` on 80 -> 8080 and `metrics` on 9090 -> 9090. `protocol` defaults to `TCP`; `UDP` and `SCTP` are the alternatives. A Service exposing both TCP and UDP on the same number needs two entries with distinct names. ## `appProtocol` `spec.ports[].appProtocol` is a hint (`http`, `https`, `grpc`, or a domain-prefixed custom value) that Kubernetes itself does not act on; ingress and mesh implementations read it to decide protocol handling. It is metadata, not behaviour. ## How this breaks in practice The classic failure is `port: 8080, targetPort: 80` written by autocomplete when the app actually listens on 8080. DNS resolves, the connection to the VIP is accepted by the dataplane, and then it hangs or is refused because nothing listens on 80 in the pod. Diagnosis is quick: `kubectl get endpointslices -l kubernetes.io/service-name=<svc>` shows the resolved `podIP:port` pairs, and `kubectl exec` into another pod plus `curl podIP:realPort` proves what the app truly listens on. If the endpoint list shows the wrong port number, the Service is misconfigured; if it shows the right one and the connection still fails, the app is probably bound to `127.0.0.1` rather than `0.0.0.0`.