Importing an Existing K3s Cluster into Rancher with the Cluster Registration Agent

Problem: You have a running K3s cluster and want to manage it alongside other environments in Rancher

Many teams run lightweight K3s clusters at the edge or in CI pipelines. Adding those clusters to Rancher manually requires recreating them, which wastes time and risks configuration drift. Rancher’s cluster registration agent lets you bring an existing K3s (or any conformant) cluster under Rancher’s view without taking over its lifecycle.

Thesis: The registration agent provides a low‑overhead, secure way to import a cluster, enable Rancher‑provided monitoring, and apply consistent RBAC while preserving the cluster’s original operational model.

How the registration agent works

When you choose “Import existing cluster” in the Rancher UI, the server generates a one‑line command that:

1. Creates a cattle-system namespace if it does not exist.
2. Deploys a DaemonSet named cluster-registration-agent that runs a tiny container.
3. The agent uses the cluster’s existing service account token to open an outbound WebSocket (secure, TLS‑protected) to the Rancher server on port 443 (or a custom TLS port).
4. Through this channel Rancher discovers nodes, workloads, and can apply its management features (monitoring catalog, RBAC sync) without installing a full Rancher‑managed control plane.

The agent is deliberately lightweight: it does not run etcd, scheduler, or controller manager, so the underlying K3s cluster continues to operate exactly as before.

Worked example: registering a self‑managed K3s cluster

Assume you have a K3s node reachable via SSH and a Rancher server accessible at https://rancher.example.com. You need a Rancher API token with the “cluster:create” privilege.

1. Generate the registration command

   In Rancher UI: Global → Clusters → Add Cluster → Import existing cluster → choose a name (e.g., edge-k3s) → click “Create”. The UI shows a command similar to:

   curl -sfL https://rancher.example.com/v3/import/xxxxxxx.yaml | kubectl apply -f -
   

   (The actual command includes a token; treat it as a secret.)

2. Run the command on the K3s node

   SSH into the node (or use any machine with kubectl configured for the K3s cluster) and execute the command with sufficient permissions to create resources in the cattle-system namespace (typically sudo or a user bound to the cluster’s admin role).

   # Example (replace placeholder with actual command)
   curl -sfL https://rancher.example.com/v3/import/xxxxxxx.yaml | sudo kubectl apply -f -
   

3. Verify the agent pod

   Check that the DaemonSet rolled out successfully:

   sudo kubectl get pods -n cattle-system -l app=cluster-registration-agent
   

   You should see one pod per node in Running state. Inspect logs for the WebSocket handshake:

   sudo kubectl logs -n cattle-system -l app=cluster-registration-agent
   

   A successful log line contains WebSocket connection established.

4. Confirm in Rancher UI

   Refresh the Clusters page. The new cluster appears under Global view. Click into it to see:

   • Nodes tab listing the K3s nodes.
   • Monitoring tab – you can enable the Rancher monitoring stack (Prometheus/Grafana) with a single toggle.
   • Apps tab – the Rancher catalog is available; you can deploy, for example, the NGINX Ingress chart:

   # From the UI, click Apps → Charts → nginx-ingress → Deploy
   

Trade‑offs and limitations

• Outbound connectivity requirement: The agent must maintain a TLS WebSocket to rancher.example.com:443. Firewall rules blocking outbound traffic will cause the agent to crashloop and the cluster will never appear in Rancher. Verify connectivity with telnet rancher.example.com 443 or a similar test before running the registration command.
• Fleet GitOps not available for imported clusters: Rancher’s Fleet continuous‑delivery system works only for clusters provisioned by Rancher RKE1/RKE2. Imported clusters can use monitoring, catalog, and RBAC, but to use Fleet you would need to re‑provision the cluster via Rancher or install the Fleet agent manually (outside the scope of this guide).
• Agent version matches Rancher server: The registration agent image is pulled from the same Rancher server version. If you run a very old K3s with a new Rancher server, ensure the agent’s compatibility matrix (generally backward compatible for a few minor versions).

Actionable closing

If you need to bring existing workloads under centralized visibility without disrupting their operation, the cluster registration agent is the simplest path. Generate the command, run it on any node with kubectl access, confirm the agent pod is running, and then enable the monitoring stack or deploy catalog apps as needed. Periodically check the agent logs and ensure outbound port 443 remains open to keep the connection healthy.