Importing an existing Kubernetes cluster into Rancher is surprisingly straightforward, but it hinges on understanding that Rancher doesn’t take over your cluster; it observes it.
Let’s see this in action. Imagine you have a kubeconfig file for your cluster, my-cluster.yaml. Rancher needs a small agent deployed into this cluster to communicate back. You can achieve this by applying a YAML manifest generated by Rancher.
First, in the Rancher UI, you’d navigate to "Add Cluster" and select "Import Existing." You’ll be prompted for a cluster name, let’s call it legacy-prod. Rancher then provides a kubectl command that looks something like this:
helm install rancher-cluster-manager https://releases.rancher.com/cluster-agent/1.0.0/cluster-agent-rancher-1.0.0.tgz \
--namespace cattle-system \
--create-namespace \
--set clusterId=c-m-xxxxxxxx \
--set "rancherApiHost=https://your-rancher-domain.com" \
--set "auditLogging.enabled=true" \
--set "fleetAgent.enabled=true"
You’d execute this command from a machine that has access to your existing cluster’s kubeconfig. The clusterId is generated by Rancher, and rancherApiHost is the URL of your Rancher server. The cluster-agent is the key component. It’s a deployment that runs within your imported cluster and establishes a secure, outbound connection to your Rancher server using the provided rancherApiHost. It essentially acts as a proxy, allowing Rancher to query cluster state and send commands.
The auditLogging.enabled=true flag ensures that all actions performed through Rancher against this cluster are logged, providing an audit trail. fleetAgent.enabled=true is crucial for enabling GitOps capabilities, allowing you to manage cluster configurations and application deployments declaratively via Git.
Once this Helm command successfully deploys the cluster-agent into your cluster, the Rancher UI will detect the agent’s registration and provisionally show your cluster as "Importing." After a few moments, it will transition to "Active."
The mental model here is that Rancher operates as a control plane external to the clusters it manages. When you import a cluster, you’re essentially telling Rancher, "Here’s an existing Kubernetes cluster, please monitor and manage it." Rancher then deploys its agent into that cluster. This agent uses the Kubernetes API within the cluster to gather information (like pod status, node health, resource utilization) and reports it back to the Rancher server. When you want to deploy an application or modify a resource via Rancher, the Rancher server translates your request into standard Kubernetes API calls, which are then sent to the cluster’s API server, often via the agent acting as a secure conduit. This decoupled architecture is what allows Rancher to manage clusters across different environments (cloud, on-premises, edge) with a consistent interface.
A common point of confusion is when you see a cluster listed as "Unavailable" in Rancher after import. This almost always means the cluster-agent deployment in the imported cluster is not running or cannot reach the Rancher API host. The most frequent culprit isn’t network policy blocking inbound connections to Rancher (because the connection is outbound from the cluster agent), but rather the cluster-agent pod itself failing to start or crashing due to incorrect configuration passed during the Helm install, or missing Kubernetes RBAC permissions it needs to function. You’d typically debug this by exec-ing into the cluster-agent pod in the cattle-system namespace of your imported cluster and checking its logs (kubectl logs <cluster-agent-pod-name> -n cattle-system).
Once your cluster is successfully imported and active, the next logical step is to explore how Rancher’s features, like centralized application catalogs and GitOps workflows via Fleet, can be applied to this newly managed environment.