docs: Note that CiliumEndpointSlice and K8s' EndpointSlice are distinct

[qmonnet]

In an attempt to lift some confusing about the similar naming of CiliumEndpointSlices and Kubernetes' EndpointSlices, and to avoid users to activate one when they only want the other, add a note to the documentation to clarify that CiliumEndpointSlice is a concept specific to Cilium, and unrelated to the Kubernetes feature.

[joestringer]

I think that the part about the two types being unrelated is accurate, but I wonder if we can try to make the core explanation here a bit more clear from a use case point of view.

[joestringer]

This is accurate to today's implementation. I'll CC @brb here as well though since I think he's investigating potential deviations on this.

[zacharysarah]

@qmonnet Nice work! ✨ Some minor edits for clarity, otherwise LGTM

[zacharysarah]

Edits for clarity.

Suggested change

	CiliumEndpointSlice is a concept that is specific to Cilium, and not related
	to `Kubernetes' EndpointSlice`_. Although the names are close, and even if
	the concept of slices in each feature brings similar improvements for
	scalability, they address different problems.
	Kubernetes' Endpoints and EndpointSlices allow Cilium to make load-balancing
	decisions for a particular Service object; EndpointSlices offer a scalable
	way to track *Service back-ends* within a cluster.
	On the other hand, CiliumEndpoints and CiliumEndpointSlices are used to make
	network routing and policy decisions. So CiliumEndpointSlices focus on
	tracking *Pods*, batching CEPs to reduce the number of updates to propagate
	through the API-server on large clusters.
	Enabling one does not affect the other.
	.. _Kubernetes' EndpointSlice: https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/
	CiliumEndpointSlice is a concept that is specific to Cilium and is not related
	to `Kubernetes' EndpointSlice`_. Although the names are similar, and even though
	the concept of slices in each feature brings similar improvements for
	scalability, they address different problems.
	Kubernetes' Endpoints and EndpointSlices allow Cilium to make load balancing
	decisions for a particular Service object; Kubernetes' EndpointSlices offer a scalable
	way to track *Service back-ends* within a cluster.
	By contrast, CiliumEndpoints and CiliumEndpointSlices are used to make
	network routing and policy decisions. CiliumEndpointSlices focus on
	tracking Pods, batching CEPs to reduce the number of updates to propagate
	through the API-server on large clusters.
	Enabling one does not affect the other.
	.. _Kubernetes' EndpointSlice: https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/

[qmonnet]

OK thanks! I always struggle to know what's best on hyphen usage on words such as “load balanc*” or “back-end”. Looks like opinions are mixed anyway, with some preference for attaching all:

$ rg -Iic 'load-balanc' Documentation | awk '{a=a+$1} END {print a}' 
75
$ rg -Iic 'load balanc' Documentation | awk '{a=a+$1} END {print a}'
72
$ rg -Iic 'loadbalanc' Documentation | awk '{a=a+$1} END {print a}' 
181

but I prefer splitting so I'll follow your suggestion.

I addressed the other suggestions too.

[zacharysarah]

@qmonnet Guidance on hyphens is mixed; I agree that it's confusing!

In this case, removing the hyphen from "load-balancing decisions" makes it clearer that the decisions are about load balancing, rather than the act of deciding somehow serving a load balancing function. Does that make sense?

[qmonnet]

Yes it does, thanks!