Cluster templates in Rancher are a powerful way to enforce standard configurations across your Kubernetes clusters, ensuring consistency and reducing operational overhead.
Let’s see a cluster template in action. Imagine you need to provision a new EKS cluster for your development team, and it must have specific node pools, a certain Kubernetes version, and a predefined set of add-ons like Prometheus and Grafana.
Here’s a snippet of a cluster template YAML that defines a downstream EKS cluster:
apiVersion: management.cattle.io/v3
kind: ClusterTemplate
metadata:
name: dev-eks-template
namespace: cattle-system
spec:
clusterConfig:
type: aks
aksConfig:
cloudProvider: azure
kubernetesVersion: 1.27.5
resourceGroupName: dev-cluster-rg
agentPools:
- name: systempool
vmSize: Standard_DS2_v2
count: 3
mode: System
- name: nodepool1
vmSize: Standard_DS4_v2
count: 5
mode: User
networkProfile:
networkPlugin: azure
serviceCidr: 10.0.0.0/16
dnsServiceIP: 10.0.0.10
dockerBridgeCidr: 172.17.0.1/16
rancherConfig:
type: cluster
cluster:
defaultPodSecurityAdmissionConfigurationTemplateName: restricted-security
enableNetworkPolicy: true
chartNamespaced:
- prometheus
- grafana
templateContent: |
apiVersion: management.cattle.io/v3
kind: Cluster
metadata:
name: dev-eks-cluster
spec:
# ... other cluster spec details ...
This template, when applied, will instruct Rancher to provision an Azure Kubernetes Service (AKS) cluster. The clusterConfig section details the cloud-specific provider configuration (Azure in this case), the desired Kubernetes version, and the node pool definitions. The rancherConfig section specifies Rancher-specific settings, such as enabling network policies and pre-installing certain Helm charts like Prometheus and Grafana. The templateContent field can be used for more granular, Kubernetes-native cluster specifications.
The core problem cluster templates solve is the "snowflake" cluster issue. Without them, each cluster provisioned manually or via separate scripts can drift in configuration. One cluster might have different node sizes, another might miss critical add-ons, and yet another might have security policies misconfigured. This leads to unpredictable behavior, difficult troubleshooting, and increased costs due to inefficient resource utilization. Cluster templates bring order by defining a desired state that all new clusters must adhere to.
Internally, Rancher uses these templates to generate the necessary cloud provider API calls and Kubernetes manifests. When you create a new cluster from a template, Rancher reads the template’s spec.clusterConfig to interact with the underlying cloud provider API (e.g., Azure API for AKS, AWS API for EKS) to provision the infrastructure. Simultaneously, it uses the spec.rancherConfig and spec.templateContent to configure Rancher’s management layer and apply Kubernetes resources within the newly provisioned cluster. This declarative approach ensures that the cluster is provisioned and configured exactly as defined in the template.
The exact levers you control are within the spec.clusterConfig and spec.rancherConfig sections. For cloud-provider-specific configurations, you’ll define things like VM sizes, disk types, network CIDRs, and auto-scaling parameters. For Rancher-specific settings, you can enforce specific Kubernetes versions, enable or disable features like network policy enforcement, define default pod security admission configurations, and select a set of default Helm charts to install. You can also parameterize templates, allowing for minor variations (like cluster names or specific node counts) while maintaining a strong baseline.
A key aspect of cluster templates, and one that often trips people up, is how they interact with existing Rancher configurations. If a template specifies a defaultPodSecurityAdmissionConfigurationTemplateName that doesn’t exist in the target cluster’s namespace or globally within Rancher, the cluster provisioning will fail. This isn’t an error in the template itself, but rather a dependency on a pre-existing Rancher resource that needs to be created before the cluster template can be successfully applied.
The next concept you’ll likely explore is how to version and manage these cluster templates effectively as your organizational standards evolve.