How do you import an existing Kubernetes cluster into Rancher?

Importing a cluster into Rancher is like registering a car with a new state. The car (cluster) already exists and runs perfectly on its own, but registering it (importing) gives you access to the state's services like license renewal, inspections, and insurance programs. Rancher does not take over the cluster; it simply establishes a management connection.

To import an existing Kubernetes cluster, you start from the Rancher global view and click 'Import Existing.' You are then prompted to choose a provider type (generic, EKS, GKE, or AKS) and provide a cluster name. For generic imports, Rancher generates a kubectl apply command containing a manifest URL. You run this command against the target cluster using a kubeconfig with cluster-admin privileges. The manifest deploys the cattle-cluster-agent and cattle-node-agent into the cattle-system namespace. These agents establish an outbound websocket connection to the Rancher management server, which is how Rancher communicates with the downstream cluster.

The agent-based architecture is significant because it means the downstream cluster does not need to be directly reachable from the Rancher server. The agents initiate the connection outward, making it possible to import clusters behind firewalls, in private VPCs, or in air-gapped networks (with additional configuration). Once connected, Rancher synchronizes the cluster state, discovers existing namespaces, workloads, and nodes, and makes them visible through the Rancher UI and API. Rancher also deploys monitoring components if the cluster meets the requirements.

In production, importing existing clusters is common during Rancher adoption. A company with existing EKS clusters running payments-api and user-auth-service does not want to recreate those clusters. Instead, they import them into Rancher to gain centralized visibility, unified RBAC, and consistent monitoring. The import process is non-destructive: existing workloads continue to run without interruption. For managed Kubernetes services like EKS, GKE, and AKS, Rancher offers native import workflows that also enable lifecycle management, meaning Rancher can upgrade the Kubernetes version and manage node pools for these clusters after import.

A gotcha that trips up beginners is certificate trust. If the Rancher server uses a self-signed certificate, the generated kubectl apply command includes a curl-based fallback that skips certificate verification. This is acceptable for initial testing but should be replaced with proper CA trust in production. Another issue is that the importing user must have cluster-admin privileges on the target cluster, which is sometimes restricted in enterprise environments. If you encounter permission errors during import, you need to coordinate with the team that manages the target cluster to grant the necessary RBAC.