Manage your self-hosted Kubernetes cluster from a single pane of glass - without tearing it down and rebuilding it.

---

Introduction

If you've been running a Kubernetes cluster bootstrapped with kubeadm and want to bring it under the management of Rancher, you're in the right place. Rancher's "Import Existing Cluster" feature makes this surprisingly straightforward — no need to destroy or rebuild your cluster.

In this blog, we'll walk through importing a kubeadm cluster into Rancher step by step. By the end, you'll have your cluster visible in the Rancher dashboard and be able to manage workloads, RBAC, monitoring, and Helm apps from one central place.

---

🖥️ Lab Environment

Here's the setup used in this guide — you can adapt it to your own IP addresses:

Role	IP Address	Description
Rancher Server	192.168.31.10	Rancher installed and accessible via HTTPS
kubeadm Node	192.168.31.20	Single-node kubeadm cluster (control-plane + worker)

---

Note: This guide assumes both machines are on the same network and can reach each other. Rancher must be accessible from the kubeadm node on port 443.

---

✅ Prerequisites

Before you begin, make sure the following are in place:

1. Rancher server is up and running - accessible via https://192.168.31.10. You should be able to log in to the Rancher UI.

2. A healthy kubeadm cluster - all nodes should be in Ready state with networking working correctly.

3. kubectl access on the kubeadm node - you need cluster-admin privileges to deploy the Rancher agent.

4. Network connectivity - the kubeadm cluster node (192.168.31.20) must be able to reach the Rancher server (192.168.31.10) on port 443.

---

📝 Step-by-Step Import Process

Step 1 - Verify kubeadm Cluster Health

SSH into your kubeadm node (192.168.31.20) and run the following commands to confirm the cluster is healthy and you have the right permissions:

export KUBECONFIG=/etc/kubernetes/admin.conf

kubectl cluster-info
kubectl get nodes
kubectl auth can-i '*' '*' --all-namespaces

Expected output for kubectl get nodes:

NAME       STATUS   ROLES           AGE   VERSION
k8s-node   Ready    control-plane   5d    v1.29.0

Expected output for kubectl auth can-i:

yes

If your node shows NotReady or you don't get yes for the auth check, fix those issues before proceeding.

---

Step 2 - Start the Import in Rancher UI

1. Open your browser and navigate to https://192.168.31.10 (your Rancher server).

2. Log in with your admin credentials.

3. Click the ☰ (hamburger menu) in the top-left corner.

4. Go to Cluster Management.

5. Click Import Existing (not "Create").

6. On the next screen, select Generic as the cluster type — this is the correct option for kubeadm clusters.

7. Give your cluster a meaningful name, e.g., kubeadm-prod.

8. Optionally, add labels or annotations (e.g., env=production, team=platform) for organizational purposes.

9. Click Create.

Rancher will now generate a unique agent deployment command for your cluster.

---

Step 3 - Run the Rancher Agent Command on your kubeadm Node

After clicking Create, Rancher displays two command options. Copy the appropriate one:

Option A - Trusted Certificate (Recommended if Rancher has a valid SSL cert):

kubectl apply -f https://192.168.31.10/v3/import/<unique-token>.yaml

Option B - Self-Signed Certificate (Use this if Rancher uses a self-signed cert):

curl --insecure -sfL https://192.168.31.10/v3/import/<unique-token>.yaml | kubectl apply -f -

⚠️ Important: The <unique-token> part of the URL is auto-generated by Rancher and is unique to your import session. Always copy it directly from the Rancher UI — never type it manually.

Go back to your kubeadm node (192.168.31.20) and paste the command. This will deploy the cattle-cluster-agent into the cattle-system namespace on your kubeadm cluster. This agent is what connects your cluster back to the Rancher server.

Step 4 - Verify the Agent is Running

After running the command, give it 60–90 seconds and then check the status of the agent pods:

bash

kubectl get pods -n cattle-system

Expected output:

NAME                                    READY   STATUS    RESTARTS   AGE
cattle-cluster-agent-xxxxxxxxx-xxxxx    1/1     Running   0          90s

If the pods are in Running state, you're good to go. If you see CrashLoopBackOff or DNS-related errors, see the Troubleshooting section below.

---

Step 5 - Confirm the Cluster Appears in Rancher

Switch back to your browser on the Rancher UI. Within a minute or two, your kubeadm cluster will appear in Cluster Management with a status of Active.

You can now:

• View all nodes, workloads, and namespaces from the Rancher dashboard

• Deploy applications using Helm charts from the Apps marketplace

• Configure RBAC and user access centrally

• Set up monitoring and alerting with Rancher's built-in tools

All of this happens without disrupting your existing workloads on the kubeadm cluster.

---

🚀 Deploy a Sample App to Verify Everything Works

Let's confirm the cluster is fully functional by deploying a simple nginx app through kubectl (still on your kubeadm node):

kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --port=80 --type=NodePort
kubectl get svc nginx

The kubectl get svc nginx command will output something like:

NAME    TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
nginx   NodePort   10.97.118.201   <none>        80:31447/TCP   10s

Now open your browser and visit:

http://192.168.31.20:31447

You should see the "Welcome to nginx!" page. You can also verify this deployment appears in the Rancher UI under your cluster's Workloads section.

---

⚠️ Common Issues & Fixes

Issue 1: ZONE_CONFLICT with firewalld and docker0

Symptom: Rancher fails to start or networking issues occur during setup.

Cause: Docker's docker0 bridge interface conflicts with firewalld zones.

Fix: Before starting Rancher, remove docker0 from firewalld zones:

firewall-cmd --zone=trusted --remove-interface=docker0 --permanent
firewall-cmd --reload

---

Issue 2: cattle-cluster-agent Pod in CrashLoopBackOff (CLBO)

Symptom: The agent pod keeps restarting and never reaches Running state.

Cause: This commonly happens on single control-plane kubeadm setups where Rancher tries to schedule multiple replicas of the agent but there aren't enough nodes.

Fix: Scale the agent deployment down to 1 replica:

kubectl scale deployment cattle-cluster-agent -n cattle-system --replicas=1

---

Issue 3: DNS Resolution Failures Inside the Agent Pod

Symptom: The agent pod crashes with DNS lookup errors when trying to reach the Rancher server.

Cause: The pod's default DNS policy doesn't resolve the Rancher server hostname correctly.

Fix: Edit the deployment and update the DNS policy:

bash

kubectl edit deployment cattle-cluster-agent -n cattle-system

Find and update (or add) these fields under the pod spec:

spec:
  template:
    spec:
      dnsPolicy: ClusterFirstWithHostNet
      hostNetwork: true

Save and exit. The pod will restart with host-level DNS resolution.

---

Issue 4: Certificate Trust Errors

Symptom: The kubectl apply -f https://... command fails with SSL certificate errors.

Cause: Rancher is using a self-signed certificate that your kubeadm node doesn't trust.

Fix: Use the insecure curl method (Option B from Step 3):

curl --insecure -sfL https://192.168.31.10/v3/import/<unique-token>.yaml | kubectl apply -f -

---

🔁 How It All Works (Under the Hood)

Understanding the mechanism helps when things go wrong. Here's what happens during the import:

1. Rancher generates a unique manifest - a YAML file containing the cattle-cluster-agent Deployment, required RBAC roles, and a Secret with the connection token.

2. You apply the manifest - kubectl apply deploys the agent into the cattle-system namespace on your kubeadm cluster.

3. The agent calls home - the cattle-cluster-agent pod establishes a WebSocket tunnel back to your Rancher server (192.168.31.10:443). This is an outbound connection from your kubeadm cluster to Rancher - so no inbound ports need to be opened on the kubeadm node.

4. Rancher registers the cluster - once the tunnel is established, Rancher can now proxy kubectl commands and resource watches through the agent, making the cluster fully manageable from the UI.

---

📌 Summary

Step	What You Do
1	Verify kubeadm cluster health and cluster-admin access
2	In Rancher UI → Cluster Management → Import Existing → Generic
3	Copy the generated command and run it on your kubeadm node
4	Verify cattle-cluster-agent pods are Running
5	Confirm the cluster appears as Active in Rancher
6	Deploy a test app to validate end-to-end functionality

---

🏁 Conclusion

Importing a kubeadm cluster into Rancher is a clean, non-destructive operation that takes less than 10 minutes. Once done, you gain centralized visibility and management across all your clusters - whether they're on bare metal, VMs, or cloud - from a single Rancher dashboard.

The key things to remember:

• Always use the Generic import type for kubeadm clusters.

• Use the insecure curl method if your Rancher server has a self-signed certificate.

• On single-node kubeadm setups, scale the agent to 1 replica to avoid CrashLoopBackOff.

• The agent uses an outbound WebSocket connection — no firewall ports need to be opened on the kubeadm node.