Rancher RKE2: Introduction on RKE2 cluster template for AWS EC2

In Rancher, you can preconfigure your clusters and node configuration. Then your team can start provisioning clusters, with consistency and no misconfiguration. For RKE, templates are easily comprehensible and seamlessly integrated into the Rancher UI, making it user-friendly. For RKE2, we need to make use of the RKE2 cluster template.

Get started with RKE2 cluster template

RKE2 cluster template

For RKE2, you need to make use of cluster templates. The cluster template is a Helm chart that you deploy into your Rancher management cluster (local) under the fleet-default namespace. Rancher will provision your cluster in the presence of these resources.

To help you understand how it works, we will deploy one RKE2 cluster on AWS EC2 using a simplified RKE2 cluster template.

Cluster specifications

The Rancher version is 2.8.2.

For our example, you need to specify a VPC ID and subnet ID. I am using a private subnet and all machines will use private IP addresses.

Also, you need to set the region and availability zone. For our example, it is set to the region eu-central-1 and availability zone a.

Templates files

The RKE2 cluster template is available at the following git repository: https://github.com/kkedbi/cluster-template-examples/tree/rke2-ec2

It is a classic Helm repository, for more information about Helm: https://helm.sh/
Let’s look into some files.

.
├── charts 
│   ├── Chart.yaml # A YAML file containing information about the chart
│   ├── README.md
│   ├── questions.yaml
│   ├── templates
│   │   ├── _helpers.tpl
│   │   ├── cluster.yaml
│   │   ├── managedcharts.yaml
│   │   └── nodeconfig-aws.yaml
│   └── values.yaml # The default configuration values for this chart
├── dbiservices-template-ec2-0.0.1.tgz
└── index.yaml

The file Chart.yaml contains the information about the chart. You can define multiple information about your chart like the name, description, versions, etc. (https://helm.sh/docs/topics/charts/).

apiVersion: v1
name: dbiservices-template-ec2
description: Cluster template for amazon ec2 rke2 
version: 0.0.1
annotations:
  catalog.cattle.io/type: cluster-template
  catalog.cattle.io/namespace: fleet-default

Note that the following annotation is mandatory to make the RKE2 Cluster template visible in Rancher.

catalog.cattle.io/type: cluster-template

The directory <templates> contains templates of the Kubernetes resources.

• cluster.yaml is for the resource cluster.provisioning.cattle.io/v1
  It contains the cluster configuration (kubernetes configuration, machine pools, update strategy, etc.)
• managedcharts.yaml contains charts to install unto the provisioned cluster.
• nodeconfig-aws.yaml contains the configuration for AWS EC2 machines.

Those files are forked from the official example GitHub repository of Rancher.
Feel free to create or edit those files to meet your needs.

An easy solution to create your template depending on your needs, is to manually create the RKE2 cluster from Rancher, and download those YAML resources files. In this way, you will be sure which parameters are used and what values to set.

The resources for the cluster and machines are available in the UI.
Cluster Management > Cluster

local > More Resources > Amazonec2Config

Installation and deployment

For the following part, fork the GitHub repository including the branch. That way you can modify the Chart files to experiment and fit your needs.

Let’s start by fixing the VPC configuration of our nodepools. In the values.yaml file, find the following parameters for both nodepools and configure it with your AWS configuration.

# AWS region
region: eu-central-1
# AWS zone for instance (i.e. a,b,c,d,e)
zone: a
# AWS VPC id
vpcId: "vpc-xxxxxxxxxxxx"
# AWS VPC subnet id
subnetId: "subnet-xxxxxxxxxxxx"

Do not hesitate to check the other parameters and modify them depending of your needs.
Once done, save the file, and run the following command to package the chart.

helm package charts
helm repo index .

git add .
git commit -m 'update values.yaml and repackage'
git push

As described in the official documentation, to use RKE2 templates, we need to add the repositories into Rancher.

In Cluster Management > Advanced > Repositories > Create.

Name: dbiservices-rke2
Target: Git repository containing Helm chart or cluster template definitions
Git Repo URL: https://github.com/kkedbi/cluster-template-examples
Git Branch: rke2-ec2

Once the repository is added, the RKE2 template will automatically be available when you create a new cluster.

Click on the dbiservices-template-ec2, it will bring you to the form to configure some of the cluster parameters.
This form is described as YAML code in Charts/questions.yaml. It is entirely customizable to fit your needs. Through the form, we can specify the Kubernetes version, CNI, VPC ID, Region, etc.

In group General, I use an AWS Credentials created in Rancher, chose RKE2 version 1.26, and Canal as Container Network.

Then you can directly configure the nodepool for controlplane and workers.

Once complete, click on install. It will install the Helm chart into the Rancher cluster (local), in the namespace fleet-default.

In case you need to remove the cluster, delete the Apps instead of the cluster. It ensures that all resources created by the Helm chart are deleted. For example, the ManagedChart is not deleted if you delete only the cluster.

Now, the cluster is provisioned with the predefined parameters in values.yaml, in addition to the customized parameters from the question.yaml form.

Conclusion

The usage of templates is not complex.
In the example above, I allowed the user to choose the Kubernetes version, the CNI, the quantity from 1 to 3 for the node pool, and their instance type. You can predefined and fix those values directly in the values.yaml or templates files.
A few fixed parameters were related to the AWS network (VPC, subnet, region, etc.). Therefore the user who uses the template doesn’t need any visibility and information about AWS configuration.

The advantage of templates is to allow users who have the rights, to create a cluster with the correct, standardized configuration, that adheres to the internal IT guidelines of your company.

Additional information

A few modifications are made in the branch rke2-ec2 of the forked repository,

For cluster.yaml, I prefixed the nodepool name with the cluster name. The purpose is to avoid errors if a nodepool already exists with the same name.

      name: {{ $.Values.cluster.name }}-{{ $nodepool.name }}

For nodeconfig-aws.yaml, I added the function quote for the parameters retries, rootSize, and spotPrice to force type string.

spotPrice: {{ quote $nodepool.spotPrice }}
retries: {{ quote $nodepool.retries }}
rootSize: {{ quote $nodepool.rootSize }}

To go further, check the next blog article about assigning members to the cluster from the template.
https://www.dbi-services.com/blog/rancher-rke2-templates-assign-members-to-clusters

Sources

• Official documentation for Cluster Template
  https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/manage-clusters/manage-cluster-templates
• My GitHub repository is a fork of the official examples repository which is denser and more complete
  https://github.com/rancher/cluster-template-examples/tree/main,.

Blogs

• RKE2 Autoscaling
  https://www.dbi-services.com/blog/rancher-autoscaler-enable-rke2-node-autoscaling/
• Reestablish administrator role access to rancher users
  https://www.dbi-services.com/blog/reestablish-administrator-role-access-to-rancher-users/
  Rancher RKE2 templates – Assign members to clusters
  https://www.dbi-services.com/blog/rancher-rke2-templates-assign-members-to-clusters