Continuing the transition from Endpoints to EndpointSlices

Since the addition of EndpointSlices (KEP-752) as alpha in v1.15
and later GA in v1.21, the
Endpoints API in Kubernetes has been gathering dust. New Service
features like dual-stack networking and traffic distribution are
only supported via the EndpointSlice API, so all service proxies,
Gateway API implementations, and similar controllers have had to be
ported from using Endpoints to using EndpointSlices. At this point,
the Endpoints API is really only there to avoid breaking end user
workloads and scripts that still make use of it.

As of Kubernetes 1.33, the Endpoints API is now officially deprecated,
and the API server will return warnings to users who read or write
Endpoints resources rather than using EndpointSlices.

Eventually, the plan (as documented in KEP-4974) is to change the
Kubernetes Conformance criteria to no longer require that clusters
run the Endpoints controller (which generates Endpoints objects
based on Services and Pods), to avoid doing work that is unneeded in
most modern-day clusters.

Thus, while the Kubernetes deprecation policy means that the
Endpoints type itself will probably never completely go away, users
who still have workloads or scripts that use the Endpoints API should
start migrating them to EndpointSlices.

Notes on migrating from Endpoints to EndpointSlices

Consuming EndpointSlices rather than Endpoints

For end users, the biggest change between the Endpoints API and the
EndpointSlice API is that while every Service with a selector has
exactly 1 Endpoints object (with the same name as the Service), a
Service may have any number of EndpointSlices associated with it:

$ kubectl get endpoints myservice
Warning: v1 Endpoints is deprecated in v1.33+; use discovery.k8s.io/v1 EndpointSlice
NAME ENDPOINTS AGE
myservice 10.180.3.17:443 1h

$ kubectl get endpointslice -l kubernetes.io/service-name=myservice
NAME ADDRESSTYPE PORTS ENDPOINTS AGE
myservice-7vzhx IPv4 443 10.180.3.17 21s
myservice-jcv8s IPv6 443 2001:db8:0123::5 21s

In this case, because the service is dual stack, it has 2
EndpointSlices: 1 for IPv4 addresses and 1 for IPv6 addresses. (The
Endpoints API does not support dual stack, so the Endpoints object
shows only the addresses in the cluster’s primary address family.)
Although any Service with multiple endpoints can have multiple
EndpointSlices, there are three main cases where you will see this:

• An EndpointSlice can only represent endpoints of a single IP
  family, so dual-stack Services will have separate EndpointSlices
  for IPv4 and IPv6.

• All of the endpoints in an EndpointSlice must target the same
  ports. So, for example, if you have a set of endpoint Pods
  listening on port 80, and roll out an update to make them listen
  on port 8080 instead, then while the rollout is in progress, the
  Service will need 2 EndpointSlices: 1 for the endpoints listening
  on port 80, and 1 for the endpoints listening on port 8080.

• When a Service has more than 100 endpoints, the EndpointSlice
  controller will split the endpoints into multiple EndpointSlices
  rather than aggregating them into a single excessively-large
  object like the Endpoints controller does.

Because there is not a predictable 1-to-1 mapping between Services and
EndpointSlices, there is no way to know what the actual name of the
EndpointSlice resource(s) for a Service will be ahead of time; thus,
instead of fetching the EndpointSlice(s) by name, you instead ask for
all EndpointSlices with a “kubernetes.io/service-name”
label pointing
to the Service:

$ kubectl get endpointslice -l kubernetes.io/service-name=myservice

A similar change is needed in Go code. With Endpoints, you would do
something like:

// Get the Endpoints named `name` in `namespace`.
endpoint, err := client.CoreV1().Endpoints(namespace).Get(ctx, name, metav1.GetOptions{})
if err != nil {
 if apierrors.IsNotFound(err) {
 // No Endpoints exists for the Service (yet?)
 ...
 }
 // handle other errors
 ...
}

// process `endpoint`
...

With EndpointSlices, this becomes:

// Get all EndpointSlices for Service `name` in `namespace`.
slices, err := client.DiscoveryV1().EndpointSlices(namespace).List(ctx,
 metav1.ListOptions{LabelSelector: discoveryv1.LabelServiceName + "=" + name})
if err != nil {
 // handle errors
 ...
} else if len(slices.Items) == 0 {
 // No EndpointSlices exist for the Service (yet?)
 ...
}

// process `slices.Items`
...

Generating EndpointSlices rather than Endpoints

For people (or controllers) generating Endpoints, migrating to
EndpointSlices is slightly easier, because in most cases you won’t
have to worry about multiple slices. You just need to update your YAML
or Go code to use the new type (which organizes the information in a
slightly different way than Endpoints did).

For example, this Endpoints object:

apiVersion: v1
kind: Endpoints
metadata:
 name: myservice
subsets:
 - addresses:
 - ip: 10.180.3.17
 nodeName: node-4
 - ip: 10.180.5.22
 nodeName: node-9
 - ip: 10.180.18.2
 nodeName: node-7
 notReadyAddresses:
 - ip: 10.180.6.6
 nodeName: node-8
 ports:
 - name: https
 protocol: TCP
 port: 443

would become something like:

apiVersion: discovery.k8s.io/v1
kind: EndpointSlice
metadata:
 name: myservice
 labels:
 kubernetes.io/service-name: myservice
addressType: IPv4
endpoints:
 - addresses:
 - 10.180.3.17
 nodeName: node-4
 - addresses:
 - 10.180.5.22
 nodeName: node-9
 - addresses:
 - 10.180.18.12
 nodeName: node-7
 - addresses:
 - 10.180.6.6
 nodeName: node-8
 conditions:
 ready: false
ports:
 - name: https
 protocol: TCP
 port: 443

Some points to note:

1. This example uses an explicit name, but you could also use
   generateName and let the API server append a unique suffix. The name
   itself does not matter: what matters is the
   "kubernetes.io/service-name" label pointing back to the Service.

2. You have to explicitly indicate addressType: IPv4 (or IPv6).

3. An EndpointSlice is similar to a single element of the "subsets"
   array in Endpoints. An Endpoints object with multiple subsets will
   normally need to be expressed as multiple EndpointSlices, each with
   different "ports".

4. The endpoints and addresses fields are both arrays, but by
   convention, each addresses array only contains a single element. If
   your Service has multiple endpoints, then you need to have multiple
   elements in the endpoints array, each with a single element in its
   addresses array.

5. The Endpoints API lists “ready” and “not-ready” endpoints
   separately, while the EndpointSlice API allows each endpoint to have
   conditions (such as “ready: false“) associated with it.

And of course, once you have ported to EndpointSlice, you can make use
of EndpointSlice-specific features, such as topology hints and
terminating endpoints. Consult the
EndpointSlice API documentation
for more information.