What is the purpose of the cluster.controlPlane.endpoint field in the controlplane.yaml?

[kubernegit]

I am trying to understand the purpose of the cluster.controlPlane.endpoint field in the controlplane.yaml.
In my scenario I run a single node talos cluster. The talos API and the kubernetes API should be accessible from different addresses. The controlplane.yaml expects a single address as endpoint like this:

# within the controlplane.yaml
cluster:
  controlPlane:
    endpoint: https://<my-adress>:6443

As I was trying to figure out which one of my addresses I should put in there I was asking myself what this is for in the first place. To allow all the addresses for TLS I can add them to the certSANs fields. Using 127.0.0.1 as endpoint seems to make no difference. Using an invalid IP address seems to work, too. I get some warnings like the following from the kernel for an invalid endpoint, but the rest seems to work.

user: warning: [2024-11-28T09:31:59.077939621Z]: [talos] kubernetes endpoint watch error {"component": "controller-runtime", "controller": "k8s.EndpointController", "error": "failed to list *v1.Endpoints: Get \"https://10.0.0.0.200:6443/api/v1/namespaces/default/endpoints?fieldSelector=metadata.name%3Dkubernetes&limit=500&resourceVersion=0\": dial tcp: lookup 10.0.0.0.200: no such host"}

What is the purpose of providing a public entrypoint address here? What feature will be missing when this is wrongly configured?

Any help is appreciated. :)

[smira]

The answer depends on the way you have your cluster configured (mostly if you disable some default features), but roughly it's the following:

• this address is used as an endpoint in the client-side kubeconfig file you receive with talosctl kubeconfig
• this address is used to derive certSANs if the endpoint is not the IP address of the node (addresses are certSANs automatically), e.g. a DNS name
• if cluster discovery is disabled (non-default setting), it would be used by worker to discover controlplane, and by controlplanes to discover other controlplanes (for etcd cluster join)
• if KubePrism is disabled (non-default settings), it would be used by workers to talk to the controlplane

So in general, Talos by default would operate just fine if you make it invalid, but it might affect cluster stability recovery under tough circumstances (e.g. if cluster discovery becomes unavailable).

Make sure the endpoint is something that other nodes in the cluster can reach the controlplane at the very least.

In a single-node scenario, none of the above matters except for certSANs.