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.

Cluster first

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"). The import.go will enqueue itself until the import service account exists, because that’s needed to create the fleet-agent-bootstrap secret. Now, the fleet-agent and the bootstrap secret are present on the downstream cluster

Fleet-Agent -> ClusterRegistration

Immediately the 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, bundledeployments and contents.

Notes

• 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-controller will 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.

Diagram

Process

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 Cluster resource with a kubeconfig. Rancher does this for downstream clusters. See manager-initiated registration.
• Create a ClusterRegistrationToken resource, optionally create a Cluster resource for a pre-defined (clientID) cluster. See agent-initiated registration.

Secrets

This diagram shows the resources created during registration and focuses on the k8s API server configuration.