Rancher can manage Kubernetes clusters it didn’t provision itself, and importing a local cluster is a common way to get started.
Let’s get a local Kubernetes cluster (like one spun up with Kind or K3s) into Rancher. We’ll use a Kind cluster for this example, but the process is nearly identical for other local setups.
First, ensure your local cluster is running and kubectl is configured to talk to it.
kind get clusters
kubectl cluster-info
Now, head over to your Rancher UI. Navigate to "Cluster Management," then click the "Import Existing" button. Rancher will present you with a command to run on your local machine. This command essentially installs a Rancher agent into your cluster.
Here’s what the command typically looks like (your specific URL and token will differ):
curl -sfL https://rancher.example.com/v3/import/xxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxx | sh -
This curl command fetches a manifest file from your Rancher server and pipes it directly into sh. The sh command then executes the manifest, which deploys the necessary Rancher agent pods into your cluster.
The manifest contains a Kubernetes Job or DaemonSet that will:
- Create a
Namespace(usuallycattle-system). - Deploy a
Deploymentof the Rancher agent pods. - Configure necessary
RBAC(ServiceAccounts, ClusterRoles, ClusterRoleBindings, Roles, RoleBindings) for the agent to communicate with the Kubernetes API server and Rancher. - Create a
Secretcontaining the registration token and your Rancher server’s URL.
Once you run the command, kubectl will apply this manifest to your local cluster. You can watch the agent pods being created:
kubectl get pods -n cattle-system -w
You should see pods like cattle-cluster-agent and cattle-node-agent start up. The cattle-cluster-agent is the primary component that registers your cluster with the Rancher server.
After a minute or two, you should see your imported cluster appear in the Rancher UI under "Cluster Management." It will initially show as "Registering" and then transition to "Active."
The most surprising thing about importing is how little you actually change in your cluster. Rancher doesn’t fundamentally alter your existing Kubernetes control plane or worker nodes. Instead, it injects a set of agents that act as a communication bridge. These agents report cluster status, node information, and listen for commands from the Rancher server. The cattle-cluster-agent is the orchestrator that talks to the Kubernetes API, and cattle-node-agent runs on each node to report node-specific health and metrics.
The core of the import process is the ClusterRegistrationToken. When you click "Import Existing," Rancher generates a unique token for your specific Rancher server. This token is embedded in the manifest it provides. When the cattle-cluster-agent starts, it uses this token to authenticate itself to your Rancher server. It then exchanges this temporary registration token for a more permanent authentication mechanism, allowing ongoing communication.
The kubectl apply -f or curl ... | sh - command is just a convenient way to deploy the Rancher agent. Under the hood, it’s applying standard Kubernetes resources: Deployments, DaemonSets, ServiceAccounts, ClusterRoles, etc. You could, in theory, manually create all these YAML manifests yourself if you knew the exact configuration Rancher expects, but using the provided command is far simpler.
The key levers you control are the Rancher server URL and the registration token. The URL tells the agent where to find your Rancher management plane, and the token authenticates the agent’s initial handshake. If these are incorrect, the agent won’t be able to register.
If you encounter issues, double-check that your kubectl context is pointing to the correct local cluster and that there are no network restrictions preventing your local machine from reaching your Rancher server URL.
The next step after importing is often configuring kubectl to manage the imported cluster directly.