Organizing nodes / clusters?

I’ve just discovered Teleport one day ago and I’m absolutely blown away by the power, easy of use and security features.

However, I’m afraid I don’t get the idea of clusters right.
I have installed one Teleport instance via docker-compose and there is one single cluster teleport (btw.: Can I rename this cluster?).
I can add / register nodes to the Teleport instance and they’re all showing up under the CLUSTER: teleport.
My intention is to organize the nodes by customer or group them based on the physical host where the nodes are running on. Can I use clusters in that manner? How can I add additional clusters and how can I choose in which cluster a node is added then?
Or are clusters meant to organize Kubernetes clusters only?

Sorry if this question seems stupid, but even after taking a look at the docs I’m still confused what a cluster is from the Teleport perspective.

Hi - firstly, thanks for trying Teleport!

Teleport’s concept of clusters (and specifically trusted clusters) is most often used when connecting different logical groups of infrastructure locations across datacenters or regions. You don’t have to deploy it this way, but bear in mind that to deploy a differently named, separate Teleport cluster would require you to run a separate Teleport auth server and then link this back to a central Teleport cluster. For this reason, it might not be the best solution.

Instead, an easy way to identify Teleport nodes is to use labels which can be set against nodes in the cluster and used for filtering. This way you could set a physical-host and/or customer label in the Teleport config file for each node that you join, then use this to get an idea of how your Teleport nodes are grouped while being inside the same Teleport cluster.

Yes, but there’s a catch. You can set the cluster_name in the /etc/teleport.yaml config file for your cluster:


Be advised however that changing a cluster name is a destructive operation, so you would need to redeploy your Teleport cluster entirely for this change to take effect. This would mean deleting the contents of /var/lib/teleport on your auth server (or deleting a Docker volume, if you’re using that for storage) then rejoining all your nodes. For this reason, it’s advisable to pick a descriptive cluster name early on in production deployments - we recommend the FQDN that can be used to access a cluster.

Thank you very much for your explanation!

Having multiple auth servers is really not what I want. I want a single point of administration for my access control and I want all session recordings to be stored on the single bastion host as well.

I have incorporated some labels and I’m able to filter my hosts the way I want. It would be nice to have some sort of predefined one-click filters available instead of having to type it into the search box every time but I can totally live with that.

I have renamed my cluster the way you described. I had only a few nodes added and it was easy to re-add them to the cluster.

Thanks again!

1 Like