Rancher Cluster Management: Choosing Between CAPI Provisioning and Cluster Import

The Infrastructure Control Decision

When integrating Kubernetes clusters into Rancher, you face a fundamental architectural choice: should Rancher own the infrastructure lifecycle, or should it act as a management overlay for clusters created elsewhere? This decision determines whether you can perform one-click scaling and version upgrades or if you must manage the underlying virtual machines and cloud APIs independently.

The core trade-off is between Full Lifecycle Management (via Cluster API) and Management Plane Only (via Importing). Choosing the wrong path often leads to operational friction, such as the inability to scale nodes from the UI or the requirement to maintain separate automation scripts for cluster upgrades.

Comparison of Management Strategies

Feature	CAPI-based Provisioning	Imported Clusters
Infrastructure Ownership	Rancher (via Cluster API)	External (Cloud/On-prem)
Node Scaling	Native via Rancher UI/API	Manual/External Tooling
K8s Version Upgrades	Automated via Rancher	External to Rancher
Credential Requirement	Cloud Provider API Keys/IAM	Kubeconfig / Agent Access
Recovery Capability	Infrastructure-level rebuilds	Application-level management

Evaluating Trade-offs

Cluster API (CAPI) Provisioning

Cluster API (CAPI) is a Kubernetes sub-project that uses declarative APIs to manage clusters. When Rancher uses CAPI, it treats your infrastructure as code. This is the preferred path for teams using public clouds (AWS, Azure, GCP) who want a single pane of glass for both the Kubernetes API and the underlying compute resources.

Key Constraint: CAPI requires high-level permissions. Rancher must be granted IAM roles or API keys capable of creating VPCs, security groups, and VM instances. If your security policy forbids granting these permissions to a management server, CAPI is not viable.

Imported Clusters

Importing involves deploying a lightweight Rancher agent into an existing cluster. Rancher communicates with this agent to provide centralized authentication, project isolation, and workload visibility, but it has no visibility into the virtual machines or the cloud account that hosts the cluster.

Key Constraint: You lose infrastructure automation. If a node fails in an imported cluster, Rancher will report the node as Unavailable, but it cannot trigger the cloud provider to spin up a replacement. You must handle node replacement, OS patching, and Kubernetes version bumps using your own CI/CD pipelines or cloud console.

Implementation and Validation

Scenario: Validating Infrastructure Control

To determine if your current cluster is correctly configured for your desired management level, perform the following validation checks. These assume you are using Rancher v2.x.

Verification for CAPI Clusters

1. Log into the Rancher UI with Administrator permissions.
2. Navigate to Cluster Management.
3. Select your CAPI-provisioned cluster and locate the Scale option.
4. Increase the node count by one.
5. Expected Result: The cloud provider's console should show a new VM instance being provisioned and joined to the cluster automatically.

Verification for Imported Clusters

1. Log into the Rancher UI.
2. Navigate to Cluster Management and select an Imported cluster.
3. Observe the absence of "Scale" or "Upgrade" buttons in the infrastructure settings.
4. Run the following command on the imported cluster's control plane to verify agent connectivity:

   # Run on the imported cluster's shell
   kubectl get pods -n cattle-system
   

5. Expected Result: The cattle-cluster-agent pod should be in a Running state. If it is CrashLoopBackOff, check the logs for connectivity issues to the Rancher server URL.

Operational Limitations

Regardless of the choice, be aware that Imported clusters cannot be converted to CAPI clusters after the fact. If you start with an import and later decide you need automated lifecycle management, you must provision a new CAPI cluster and migrate your workloads. Conversely, CAPI clusters can be managed more loosely, but the infrastructure ownership remains with the Rancher management plane.