Importing Existing Clusters

Import existing Kubernetes clusters into Rancher for centralized management

Rancher allows you to import existing Kubernetes clusters and manage them through the Rancher UI. Imported clusters maintain their existing configuration while gaining access to Rancher’s management features.

Overview

When you import a cluster, Rancher:

• Deploys the cluster agent to establish communication
• Creates a management relationship without modifying the cluster’s core infrastructure
• Enables centralized access control, monitoring, and workload management

Imported clusters are identified with the driver type imported (defined as ClusterDriverImported in /home/daytona/workspace/source/pkg/apis/management.cattle.io/v3/cluster_types.go:76).

Prerequisites

• An existing Kubernetes cluster
• kubectl access to the cluster with cluster-admin privileges
• Network connectivity from the cluster to the Rancher server
• The cluster’s kubeconfig file

Import Process

1. Create the Imported Cluster in Rancher
3. Generate the Registration Command
4. After creating the cluster, Rancher generates a registration token and provides kubectl commands to apply the agent manifest.
5. The registration process:
7. See Registration Tokens for details on token management.
8. Apply the Agent Manifest
9. Rancher provides two commands based on your cluster’s certificate configuration:
10. Secure command (for clusters with valid CA certificates):
11. curl --insecure -sfL {RANCHER_URL}/v3/import/{TOKEN}.yaml | kubectl apply -f -
    

12. Insecure command (for development or self-signed certificates):
13. curl -sfL {RANCHER_URL}/v3/import/{TOKEN}.yaml | kubectl apply -f -
    

14. The insecure command skips TLS verification. Only use this in development environments or when your Rancher server uses self-signed certificates.

15. The command:
17. Verify the Import
18. After applying the manifest:
20. You can verify the agent deployment:
21. kubectl get pods -n cattle-system
    

22. Expected output:
23. NAME                                    READY   STATUS    RESTARTS   AGE
    cattle-cluster-agent-xxxxxxxxxx-xxxxx   1/1     Running   0          2m
    

Cluster Configuration

Imported clusters use the ImportedConfig specification:

type ImportedConfig struct {
    KubeConfig         string  // Base64-encoded kubeconfig (password field)
    PrivateRegistryURL string  // Private registry URL for pulling images
}

Source: /home/daytona/workspace/source/pkg/apis/management.cattle.io/v3/cluster_types.go:183

Private Registry Support

If your cluster requires a private registry for pulling Rancher agent images:

1. Specify the privateRegistryURL during import
2. Rancher configures the agent to use this registry
3. Ensure the registry contains the required agent images

The agent image is resolved using the cluster’s private registry configuration when available.

Agent Components

The import process deploys:

• cattle-cluster-agent: Primary agent for cluster communication
• cattle-node-agent: Node-level agent for node management (if applicable)

These agents:

• Establish secure websocket connections to Rancher
• Synchronize cluster state and resources
• Execute operations requested through the Rancher UI
• Report cluster metrics and health status

Network Requirements

• Outbound: The cluster must reach the Rancher server URL
• Ports: HTTPS (443) or custom port if configured
• Proxy: Configure HTTP_PROXY/HTTPS_PROXY in agent environment variables if needed

Cluster Capabilities

After import, Rancher detects and reports cluster capabilities:

• Load balancer support
• Ingress controllers
• Node port range
• Storage classes
• Taint support

These capabilities determine which Rancher features are available for the cluster.

Post-Import Operations

Once imported, you can:

• Generate kubeconfig files for kubectl access
• Rotate certificates (for supported cluster types)
• Configure backup schedules (for RKE clusters)
• Deploy workloads through Rancher
• Configure monitoring and alerting
• Manage cluster members and RBAC

Limitations

• Imported clusters cannot be upgraded through Rancher
• Cluster infrastructure modifications must be performed outside Rancher
• Some operations (like etcd backup) are only available for RKE clusters
• Certificate rotation is limited to RKE2/K3s clusters

Troubleshooting

Agent Fails to Connect

1. Verify network connectivity from the cluster to Rancher
2. Check the agent logs:
   kubectl logs -n cattle-system -l app=cattle-cluster-agent
   
3. Verify the registration token hasn’t expired
4. Ensure the Rancher server URL is accessible from the cluster

Cluster Stuck in “Pending” State

• The agent deployment may not have been applied
• The agent may be failing to start (check pod status)
• Network policies may be blocking agent communication

Certificate Errors

• Use the insecure command if Rancher uses self-signed certificates
• Configure custom CA certificates in the cluster if needed

Related Resources

• Registration Tokens
• Kubeconfig Access
• Cluster API Reference