Kubernetes Endpoint Definition

Kubernetes Endpoint Definition is the precise characterization of an Endpoints object, and its current successor the EndpointSlice, as the API record that actually enumerates the concrete network addresses backing a Service, formally distinct from the Service object itself, which declares only a selector and never directly lists addresses. Where a Service expresses intent, "route to whatever matches this selector," the Endpoints or EndpointSlice object is the derived, continuously updated answer to that intent: the literal list of IP addresses and ports currently eligible to receive traffic.

Formal Relationship to Services

Derived, Not Declared

An Endpoints or EndpointSlice object is not authored directly by a user in the normal case; it is computed and continuously maintained by a controller that watches a Service's selector and the Pods matching it, formally making it a derived artifact rather than an independent source of intent.

Same Name as the Service

An Endpoints object formally shares its name with the Service it corresponds to, a fixed convention that allows any client to locate a Service's current address list by looking up an Endpoints object of the identical name, rather than through any explicit cross-reference field.

kubectl get endpoints codartium-api
kubectl get service codartium-api

Endpoints vs. EndpointSlice

The Original Endpoints Object

The original Endpoints API represents every backing address for a Service within a single object, which formally becomes a scalability constraint for Services backed by very large numbers of Pods, since any single change requires rewriting the entire, potentially large, address list.

EndpointSlice

EndpointSlice formally partitions a Service's backing addresses across multiple, smaller objects, each capped at a bounded number of entries, allowing updates to be scoped to only the affected slice rather than requiring a rewrite of the Service's entire address set, and additionally carries topology information not present in the original Endpoints schema.

apiVersion: discovery.k8s.io/v1
kind: EndpointSlice
metadata:
  name: codartium-api-x7f2q
  labels:
    kubernetes.io/service-name: codartium-api
addressType: IPv4
ports:
  - name: http
    port: 8080
endpoints:
  - addresses: ["10.244.1.7"]
    conditions:
      ready: true

Readiness as a Formal Inclusion Criterion

Ready vs. Not Ready Addresses

Inclusion of a Pod's address in the ready set of an Endpoints or EndpointSlice object is formally gated by that Pod's Ready condition; a Pod matching a Service's selector but failing its readiness probe is either omitted from the ready address list or recorded separately as not-ready, depending on the API version, and therefore does not formally receive traffic distributed by kube-proxy.

How Endpoints Are Consumed

kube-proxy

kube-proxy formally watches Endpoints/EndpointSlice objects on every node and programs local packet-forwarding rules, iptables or IPVS entries, that implement the actual redirection of traffic sent to a Service's virtual IP toward one of the currently ready addresses recorded there.

Cluster DNS

Cluster DNS, in the case of headless Services, resolves queries directly against the addresses recorded in the corresponding Endpoints/EndpointSlice object, rather than returning a single virtual IP, formally exposing the underlying address list directly to DNS clients.

kubectl get endpointslices -l kubernetes.io/service-name=codartium-api -o wide

Manually Managed Endpoints

Services Without a Selector

A Service defined without a spec.selector formally produces no automatically managed Endpoints object; in this case, an Endpoints object with the same name may be created and maintained manually, or by an external controller, allowing a Service to represent a set of addresses that exist entirely outside the set of Pods the cluster itself schedules, such as an external database.

apiVersion: v1
kind: Endpoints
metadata:
  name: external-db
subsets:
  - addresses:
      - ip: 203.0.113.42
    ports:
      - port: 5432

This manual case formally illustrates that the Endpoints object, not the Service selector, is what kube-proxy and DNS actually consume, the selector-driven derivation is simply the default, automated way that record is populated.