Decision Guide: Using Rancher Cluster Templates vs. Import or Ad‑hoc UI Clusters

Decision and Constraints

You need a repeatable way to provision Kubernetes clusters that can be version‑controlled, requires minimal ongoing admin effort, and works with the node infrastructure you already support (e.g., Ubuntu 20.04, Amazon Linux 2, or CentOS 7). The decision is whether to define a Rancher Cluster Template, import an existing cluster, or create a one‑off cluster via the Rancher UI.

Constraints

• Rancher server version ≥ 2.5 (for basic templates) or ≥ 2.6 if you plan to use RKE2/K3s‑specific templates.
• Access to the Rancher API or UI with a token that has the cluster-admin role (or equivalent).
• Underlying node hosts must run a supported Linux distribution and have network access to the Rancher server.

Options Comparison

Option	Setup Effort	Version Control	Flexibility	Typical Use Case
Cluster Template	Low (once defined)	High (YAML stored in Git)	Medium (limited to exposed parameters)	Standardized, repeatable clusters across environments
Import Existing Cluster	Medium	Low (cluster lives outside Rancher’s declarative model)	High (bring any conformant cluster under Rancher)	On‑boarding brownfield clusters or third‑party hosted K8s
Custom Cluster via UI	Low (ad‑hoc)	Low (no artifact stored)	High (full UI‑driven customization)	Testing, experiments, or short‑lived workloads

Trade‑offs

Cluster Templates give you reproducibility and the ability to track changes in Git, but they require upfront authoring and only expose the parameters you deliberately define in the template. Node‑pool customization is limited to what the template exposes; any deviation requires a new template version.

Importing an existing cluster provides maximal flexibility because you can bring any conformant cluster under Rancher’s UI, but you lose Rancher‑driven lifecycle management (e.g., automated upgrades, node‑pool scaling via Rancher). Drift detection is harder because the cluster’s original provisioning method remains outside Rancher’s control.

Ad‑hoc UI clusters are the fastest way to get a test cluster running, but they hinder auditability and make it difficult to enforce standards or detect configuration drift over time.

Concrete Implementation: Creating an RKE2 Cluster Template

The following steps show how to define a template for an RKE2 cluster running Kubernetes v1.27 with two etcd nodes and three worker nodes using Amazon Linux 2 AMIs, then apply it via the Rancher API.

1. Author the Template YAML

Save this as rke2-amazonlinux2-template.yaml. Replace placeholder values with your own.

# rke2-amazonlinux2-template.yaml
apiVersion: provisioning.cattle.io/v1
kind: ClusterTemplate
metadata:
  name: rke2-amazonlinux2-k8s1.27
spec:
  description: "RKE2 Kubernetes v1.27 on Amazon Linux 2"
  rancherKubernetesEngineConfig:
    type: "rke2"
    rke2Config:
      kubernetesVersion: "v1.27.0+rke2r1"
      # etcd nodes
      etcd:
        arg:
          - "--snapshotter=v2"
        # two etcd hosts will be filled in by node templates
      # worker nodes
      worker:
        arg:
          - "--kubelet-arg=eviction-hard=memory.available<100Mi"
    # Node templates reference cloud credentials and AMI
    nodeTemplates:
      - etcd:
          count: 2
          template:
            amazonec2config:
              accessKey: 
              secretKey: 
              region: us-east-1
              ami: ami-0abcdef1234567890  # Amazon Linux 2
              instanceType: t3.medium
              iamInstanceProfile: nodes.profile
              sshUser: ec2-user
      - worker:
          count: 3
          template:
            amazonec2config:
              accessKey: 
              secretKey: 
              region: us-east-1
              ami: ami-0abcdef1234567890
              instanceType: t3.large
              iamInstanceProfile: nodes.profile
              sshUser: ec2-user

2. Apply the Template via the Rancher API

Run the following curl command from a workstation that has network access to the Rancher server. You need an API token with the cluster-admin role.

# Replace placeholders
RANCHER_URL="https://rancher.example.com"
TOKEN=""
TEMPLATE_FILE="rke2-amazonlinux2-template.yaml"

curl -k -X POST "${RANCHER_URL}/v3/clustertemplates" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/yaml" \
  --data-binary @${TEMPLATE_FILE}

Expected response: HTTP 201 Created and a JSON body containing an id field (e.g., c-tx9z2). The response also includes a state field that will be provisioning initially.

3. Provision a Cluster from the Template

Once the template exists, create a cluster that uses it.

CLUSTER_TEMPLATE_ID="c-tx9z2"  # from previous step
CLUSTER_NAME="prod-rke2-us-east-1"

curl -k -X POST "${RANCHER_URL}/v3/clusters" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cluster",
    "name": "'${CLUSTER_NAME}'",
    "clusterTemplateId": "'${CLUSTER_TEMPLATE_ID}'",
    "rancherKubernetesEngineConfig": {}
  }'

Again, expect HTTP 201. The cluster will begin provisioning; you can monitor progress via the UI or by polling GET /v3/clusters/ until state becomes active.

Validation Steps

After the cluster reaches active state, verify that it matches the template definition.

API‑based Check

CLUSTER_ID="c-abcd1234"
curl -k -s "${RANCHER_URL}/v3/clusters/${CLUSTER_ID}" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.state, .appliedSpec.rancherKubernetesEngineConfig'

Look for "state": "active" and confirm that appliedSpec.rancherKubernetesEngineConfig.rke2Config.kubernetesVersion matches v1.27.0+rke2r1.

kubectl‑based Node Verification

Fetch the cluster’s kubeconfig from Rancher (you can do this via the UI or API) and store it as kubeconfig-prod. Then:

export KUBECONFIG=./kubeconfig-prod
kubectl get nodes -o wide

You should see five nodes total: two with the etcd role and three with the worker role, all reporting Ready. The OS IMAGE column should show Amazon Linux 2.

Optional Monitoring Stack Check

If you enabled the Rancher monitoring chart in the template, run:

kubectl get pods -n cattle-monitoring-system

All pods should be Running (or Completed for init containers).

Limitations and Practical Checks

• Version compatibility: The template’s RKE2/K3s version must be supported by your Rancher server. Using a template for RKE2 v1.27 on Rancher < 2.65 may cause the controller to skip the deployment or produce errors. Verify compatibility in the Rancher release notes before applying.
• Credential exposure: Cloud API keys embedded in the template YAML are treated as secrets. Never commit raw keys to a public repository; instead, store them in a secret manager (e.g., HashiCorp Vault, AWS Secrets Manager) and reference them via secret fields or external credential stores when creating the template.
• Node‑pool flexibility: If you need to add a custom label or taint that is not exposed in the template, you must create a new template version. There is no direct “patch” operation for existing clusters created from a template.
• Drift detection: Rancher will report drift only for fields that are part of the template’s schema. Changes made directly on the cloud provider (e.g., manually resizing an EC2 instance) will not be detected until you re‑apply the template or manually reconcile.

To check that your template remains the source of truth, periodically compare the cluster’s appliedSpec (via the API) with the original template YAML. Any divergence outside of user‑editable fields indicates drift that should be addressed.