Rancher Import vs. Provision: Who Owns the Cluster Lifecycle?

You install Rancher, add a kubeconfig, and the dashboard offers two doors: Import Existing or provision a new cluster. The choice looks like a UI preference. It is actually a contract about who is allowed to upgrade the control plane, who holds the cluster spec, and what happens when the Rancher manager itself is unavailable.

The thesis here is simple: decide the ownership question first, then pick the button. Teams that pick the button first usually discover the mismatch months later, during an upgrade window.

What each path actually delegates

Rancher is a management plane. It does not sit in the data path of your workloads — it talks to each downstream cluster's API server through an agent. What differs between the two paths is how much of the cluster's lifecycle Rancher is responsible for.

Aspect	Provisioned by Rancher	Imported into Rancher
Cluster spec stored in	Rancher (as a Rancher object)	The cluster's own tooling
Control-plane upgrades	Driven through Rancher for supported distros such as RKE2 and K3s	Owned by whoever built the cluster
Node bootstrap	Rancher-driven	Unchanged
Agent footprint	Cluster agent plus node agent	Cluster agent plus node agent

Both paths install the same connection components into the cattle-system namespace: a cattle-cluster-agent Deployment that maintains the connection to the Rancher manager, and a cattle-node-agent DaemonSet used for node-level operations. The agent dials out to the manager over HTTPS, which is why importing a cluster behind NAT generally works without inbound firewall rules — but it also means the downstream cluster must trust the manager's certificate and be able to reach it.

That outbound-only design has a useful consequence worth internalizing: if the Rancher manager goes down, existing workloads in downstream clusters keep running. You lose management, policy application, and the dashboard — not the applications.

Worked example: importing a cluster and proving the connection

This is the path most teams take when clusters already exist. Run all commands against the target cluster, not the Rancher manager.

Prerequisites: a Rancher manager reachable at a stable hostname with a certificate the target cluster trusts; a kubeconfig with cluster-admin on the target cluster; outbound TCP 443 from the target cluster to the manager. If the manager uses a self-signed certificate, plan for how the agent will trust it before you start.

1. In the Rancher UI, go to Cluster Management → Import Existing, choose the provider type (Generic for a self-managed cluster), give it a name, and create it.
2. Copy the generated kubectl apply command. Its shape is:
   

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

   The token is generated per registration and can expire. If the apply fails with an authorization error, regenerate the command in the UI rather than reusing the old one.
3. Apply it with an explicit context so you do not hit the wrong cluster:
   

   kubectl --context <target-context> apply -f https://<RANCHER_HOST>/v3/import/<token>.yaml

4. Verify the agents landed:
   

   kubectl --context <target-context> -n cattle-system get deploy cattle-cluster-agent
   kubectl --context <target-context> -n cattle-system get ds cattle-node-agent

   Check that the Deployment reports its replica as available and that the DaemonSet's ready count matches the number of schedulable nodes. Exact column values vary by Kubernetes version; the point is that desired equals ready.
5. If the cluster agent is not available, read its logs:
   

   kubectl --context <target-context> -n cattle-system logs deploy/cattle-cluster-agent

   The common causes are certificate trust, an egress proxy that is not configured for the agent, blocked outbound 443, and clock skew large enough to break TLS.

Then verify that RBAC actually propagated

Importing a cluster is easy to confirm visually. RBAC propagation is the part people assume works and rarely test. Rancher maps users and groups onto downstream Kubernetes roles through Projects, which group one or more namespaces.

1. Create a Project in Rancher and assign it a namespace in the imported cluster.
2. Add a test user as Project Member.
3. Download that user's kubeconfig from Rancher and run:
   

   kubectl --kubeconfig <user-kubeconfig> auth can-i list pods -n <namespace>
   kubectl --kubeconfig <user-kubeconfig> auth can-i get nodes

The expected result is an affirmative answer for the namespaced action and a negative one for the cluster-scoped action. If the first is negative, the role binding did not reach the downstream cluster — check that the user was added to the right Project rather than only to the cluster, and that the namespace is actually assigned to that Project.

Trade-offs and limits worth knowing before you commit

• The manager is a single point of failure for management, not for workloads. A single-node Rancher install means orchestration, policy, and the dashboard are unavailable if that node fails. High-availability installations spread the manager across multiple nodes; the cost is more infrastructure and a more involved certificate and backup story.
• Version skew is real. Each Rancher release supports a documented range of downstream Kubernetes versions. Upgrading the manager and the clusters out of step is a common source of trouble. Check the support matrix for your exact Rancher version before either upgrade.
• Imported clusters from managed services keep their own upgrade path. Rancher will not upgrade the control plane of a cluster whose lifecycle belongs to a cloud provider. Your upgrade button now lives in two places, and someone has to own the coordination.
• Air-gapped environments need more than a firewall rule. The agent images must be pullable from a registry the cluster can reach, which usually means a mirrored private registry.

Verify before you rely on it: supported Kubernetes version ranges, agent image names, and registration token behavior change between Rancher releases. Confirm the specifics against the documentation for the version you are running rather than treating the above as fixed.

The decision, in one question

Ask who is permitted to touch the control plane. If the answer is "Rancher," provision the cluster so Rancher holds the spec and drives upgrades. If the answer is a platform team, a cloud provider, or an existing automation pipeline, import the cluster and treat Rancher as the policy, RBAC, and visibility layer. Either way, run the two auth can-i checks after onboarding — they take a minute and catch the failure mode that otherwise surfaces as a support ticket from a user who cannot see their own namespace.