Version upgrade of an RKE2 cluster
Today we are going to talk about the possibility of changing the version of a Kubernetes cluster based on Rancher Kubernetes Engine (hereafter RKE2).
We have recently worked with projects that required an update to the Kubernetes version, yet there may also be the case of you having microservices developed that require an earlier version. All of this problem, although documented on the RKE2 website itself, is quite sensitive, and some things must be taken into account to carry this out so that it causes the least possible impact.
What is RKE2?
First of all, RKE2 is a Kubernetes distribution developed by Rancher. In addition to security improvements, the main difference with its predecessor is that it is no longer based on Docker.
The resources associated with the cluster’s ControlPlane are deployed as static pods orchestrated using kubelet, and the rest of the cluster’s resources use ContaiNerd (currently the standard option for container orchestration). Installing and deploying RKE2 is quite simple if you do not apply any custom configuration. It is completely compatible with any Linux distribution, allowing it to be installed without having to configure anything specifically for the distribution.
If you are interested in deploying your own cluster based on RKE2, you can follow the steps indicated in the documentation on their website.
Changing RKE2 version
Once you have a Kubernetes cluster based on RKE2, you may want to change its version for a number of reasons. This process is the same for both upgrading and downgrading to another version, which makes things easier in case there is any problem with an update due to compatibility issues. RKE2 itself is releasing updated versions mostly with changes to the Kubernetes version (although also with the RKE2 version itself). All of these versions can be found in their Github repository in the format v[kubernetes version]+[rke2 version].
With this in mind, we are going to describe the most important steps for any version change. These changes will have to be applied separately to each node in the cluster. If all these steps are followed, at the end of the entire process the cluster will be able to start without any problem (as if you had simply restarted it) and all the associated resources will have been kept just as they were before.
Steps to change version
As we mentioned previously, these steps must be followed for each existing node in the cluster. It is important that they are followed in order and executed correctly.
Let’s follow the process from a test environment created in which you have two nodes. In this case, you will update the server version, but the steps are the same if you wanted to change the agent.
In the following screenshot, you can see how you start from the Kubernetes version v1.24.11 and the RKE2 rke2r1 and, in this case, you will update to the Kubernetes version 1.26.7.
First, it is important to stop all processes running on the node. In this way, you ensure that no process interferes with the process and could lead to errors. For this step, by default with the installation of RKE2, a script called rke2-killall.sh is created. Hosted in the path «/usr/local/bin», it will be responsible for stopping all the node processes. Once executed, the rke2 service (server or agent, depending on the case) will be stopped.
/usr/local/bin/rke2-killall.sh
service rke2-server stopOnce this process is done, proceed with updating the RKE2 service. To do this, use the script provided by RKE2, setting, at least, the following variables:
- INSTALL_RKE2_METHOD: this variable will set the method by which RKE2 was previously installed. By default, it will be «tarball» (tar).
- INSTALL_RKE2_TYPE: this other variable will be set depending on whether you want to update a node of the server or agent type.
- INSTALL_RKE2_VERSION: this third variable will define the version of Kubernetes and RKE2 to which you want to update with the following format: vX.Y.Z+rke2rN. If the version is not set, it will be updated to the latest stable version released.
For this example, set the variables with the following values and in the following way:
export INSTALL_RKE2_METHOD=tar
export INSTALL_RKE2_TYPE=server
export INSTALL_RKE2_VERSION=v1.26.7+rke2r1Once these variables are set, download the script, give it the necessary permissions and execute it.
curl -sfL https://get.rke2.io > /tmp/rke2-script.sh
chmod 755 /tmp/rke2-script.sh
/tmp/rke2-script.shWhen the script is executed, you can restart the RKE2 service and verify that the version is the one you have set.
service rke2-server start
rke2 --versionCheck that the deployed version is the one we had set in the variables, and this completes the node update.
As we mentioned previously, if you want to update an agent-type node, the process is the same. Furthermore, if you want to deploy a lower version of Kubernetes, it would also be possible without a problem, since this process supports both upgrading and downgrading versions.
Beer in mind that, if the previous installation had some type of custom configuration (for example the RKE2 services execution directory), it would be lost with this update, and you would have to be customize it again.
Conclusions
RKE2 is an optimal, very used solution for setting up a Kubernetes cluster. Although its documentation is very useful, it can sometimes overlook some details.
By following this tutorial, you can change the RKE2 version without problems, facilitating both the Kubernetes version update, and a possible rollback if needed. As we have shown, this process seems simple, but it is very important to follow the steps strictly, since in case of failure, data can be lost.
✍🏻 Author(s)
