Cluster Registration Internals
How does cluster registration work?
This text describes cluster registration with more technical details. The text ignores agent initiated registration, as it’s not commonly used.
Agent initiated registration is "
ClusterRegistrationToken first", which means pre-creating a cluster is optional.
See "Register Downstream Clusters" to learn how to register clusters.
fleet-controller starts up and may "bootstrap" the local cluster resource. In Rancher creating the local cluster resource is handlded by the fleetcluster controller instead, but otherwise the process is identical.
For manager initiated registration the process is identical for the local cluster or any downstream cluster. It starts by creating a cluster resource, which refers to a kubeconfig secret.
Cluster -> ClusterRegistrationToken + Import Account
Now that a cluster resource exists,
fleet-controller triggers and runs
import.go to create the fleet-agent deployment.
fleet-controller also creates a
clusterregistrationtoken and waits for it to be complete. The
clusterregistationtoken triggers the creation of the import service account, which can create
clusterregistrations and read any secret in the system registration namespace (eg "cattle-fleet-clusters-system").
import.go will enqueue itself until the import service account exists, because that’s needed to create the
fleet-agent and the bootstrap secret are present on the downstream cluster
Fleet-Agent -> ClusterRegistration
fleet-agent checks for a
fleet-agent-bootstrap secret (which contains the import kubeconfig) and starts registering if present. Then
fleet-agent creates a clusterregistration resource in fleet-default on the management cluster, with a random number. The random number will be used for the registration secret’s name.
fleet-controller triggers and tries to grant the clusterregistration request to create
fleet-agent’s serviceaccount and create the
‘c-*’ registration secret with the clients new kubeconfig.
The registration secret name is
hash("clientID-clientRandom"). The new kubeconfig uses the "request" account. The request account can access the cluster status,
- The registration starts with the "import" account and pivots to the "request" account.
- The fleet-default namespace has all the cluster registrations, the import account uses a separate namespace.
- Once the agent is registered,
fleet-controllerwill trigger on a cluster/namespace change and call manageagent to create a bundle. The agent will update itself to the bundle and since the generation env var changes it will restart.
- If no bootstrap secret exists, the agent will not re-register.
Detailed analysis of the registration process for clusters. This shows the interaction of controllers, resources and service accounts during the registration of a new downstream cluster or the local cluster. It's important to note that there are multiple ways to start this:
- Creating a bootstrap config. Fleet does this for the local agent.
- Creating a
Clusterresource with a kubeconfig. Rancher does this for downstream clusters. See manager-initiated registration.
- Create a
ClusterRegistrationTokenresource, optionally create a
Clusterresource for a pre-defined (
clientID) cluster. See agent-initiated registration.
This diagram shows the resources created during registration and focuses on the k8s API server configuration.