Getting started with Rancher Desktop, containerd and K3S clusters

Working on the right version of Kubernetes is very important. Also, the ability to replicate for dev and test environments a multi-node cluster topology, as close (if not identical) to the one that we use in production. This is because even small versions between kubernetes clusters contain changes in their APIs that can cause unexpected behaviours. For example, beta API versions upgrading to GA – That’s enough to break everything.  The quickest answer to this challenge is to run kubernetes in a cloud provider, replicating clusters for dev and test and keeping them aligned in terms of versions and configurations. Although in practice this is fine, for dev in particular, this represents an unnecessary over spend that can slow down the development process.

As a devops engineer, I would prefer to be able to run it on my Mac (or PC) and treat it like any other embedded runtime. I can use minikube, but then it lets me create only 1 non-production worker node cluster. In the past, we leveraged other virtualization techniques to create multi-node deployments, but it was harder to support and a bit inflexible. 

I never found a flexible approach to make it happen, until new technologies like Containerd and Rancher’s k3s (lightweight certified kubernetes distribution – read more about it here) make it possible to run multi-node clusters locally very easily. Rancher Desktop, is a tool that simplifies all of this together for Mac and Windows users.

In a nutshell, Rancher Desktop provides an easy way to spin up containerd kubernetes clusters for Mac and Windows and it covers the full range of container management locally.

Let’s get started.

In this blog, I assume the following:

  • You are familiar with containers and Kubernetes in general. If you need a refresher, have a look at one of my  previous blogs.
  • This blog is just my personal opinion and experience. For the official Rancher Desktop documentation and messaging, go to the Rancher website.

 Introducing Rancher Desktop

As mentioned, Rancher desktop provides a seamless experience for Mac and Windows users to manage containers lifecycle and spin up kubernetes clusters.  Let’s review some of its most important 3 characteristics:

  1. You can choose the version of Kubernetes – This is great to ensure alignment with Production, as well as ensuring that future Kubernetes upgrades will not break the running applications.
  2. CPU and Memory allocation – Simple way to set the virtual size of our worker nodes.
  3. Build and run container images in Kubernetes without the need to push /pull from an image registry – Again, this is ideal when developing applications, saving lots of unnecessary image transferring time. This is done via the use of KIM cli (Kubernetes Image Manager), that uses containerd internally. We are going to test this functionality later in this blog.

Exploring Rancher Desktop

First, let’s get Rancher Desktop installed:

  • That is super easy, just go to the Rancher Desktop website, click on the “Download button” and choose the version to download (I recommend always to get the latest version – unless you know better)
  • Pick the distribution based on your equipment. So far they support Mac, Windows and Linux. Also, at the time of writing this blog, the latest version is v0.6.0 and the download is around 250MB for Mac.
  • Then just follow the steps to get it installed.
  • Once installed, give it a minute or 2 to download kubernetes and other dependencies.

Note: Ok, now, don’t ask me why, but you need to restart your laptop… I’ve tried multiple times to understand exactly the process that needs to be restarted to avoid restarting the whole laptop. Anyway, look, it is once off restart and then it works like a charm. Once I understand how to avoid this ugly step, I will share it with you.

  • Now, simply start “Rancher Desktop”. Depending on your cluster configuration and machine spec it can take a few minutes, but it should be pretty quick. In the background, it will start kubernetes and symlink all required dependencies.
  • As mentioned, you can choose from a version of Kubernetes cluster to run
  • Notice that when changing the version of the Kubernetes cluster upwards, Rancher Desktop will automatically download any required dependency and apply it to the cluster by keeping your current assets deployed. This way you can test your microservices on the newer version. If you use an older version, it will remove and create the cluster.
  • As well as to assign CPU and memory resources to your cluster
  • At any point in time, you can delete and re-create your cluster, by clicking “Reset Kubernetes”.

Building and testing your containers

As I mentioned, behind the scenes, Rancher is using containerd and k3s kubernetes distro – It automatically configures helm, kim and nerdctl cli for image management. 

Nerdctl is a Docker – compatible CLI for containerd – You can read more about it here. – But basically, it follows the same logic and capability as docker cli to build and run containers. If you know docker cli, you know nerdctl. It also lets you do more functions, currently supported by containerd, but not by docker cli, such as image lazy pulling and encryption of images… So I definitely recommend that you look into it.

Rancher Desktop will bring and configure symbolic links to various clis, including: helm, kim and nerdctl

In order to make sure that this is properly configured, make sure that you are ticking the symbolic link boxed in the “Supporting Utilities” section. Also, it is possible that you already have an existing installation and configuration of helm or kubectl – If so, Rancher Desktop will not override it. You would need to remove those symbolic links manually if you wanted to use those from Rancher Desktop.  Like in my case, I selected all except kubectl, which I already had it configured previously… 

  • Ok, now, let me show you that nerdctl is very similar to docker cli… For example, let’s run an alpine container: In a terminal enter:
nerdctl run -it –rm alpine
  • Great, what about building your own image from an existing Dockerfile via nerdctl?
git clone
cd hello-microservices/nodejs-ms/
  • Feel free to explore the Dockerfile – It is pretty standard. It just build from a nodejs 9.11.1 image, adds the hello world project, runs dependencies and starts the nodejs application – Easy peasy!
  • Ok, well let’s build our image with nerdctl – Just as we would do with docker cli
nerdctl build -t carlosimage .
  • After a minute or two, your image will be built. You can see the list, as you would typically do with a docker cli.
nerdctl images
  • So far, I can see the alpine image that I used before and the new one I just built. 
  • Now, let’s run it:
nerdctl run -it -rm -p 3000:3000 carlosimage
  • Yay, our nodejs application is working.  It doesn’t do much though, but feel free to go on a browser of curl localhost:3000
  • Notice that we are not seeing all the containers for the running kubernetes cluster. That is because containerd runs those in a different namespace. If we wanted to see them:
nerdctl –namespace ps
  • Also, you can jump back into the Rancher Desktop preferences and see within “Images” all the different images split by namespaces:
  • Switch to the default namespace to see the image that we built earlier:
  • This means that we can already use kubectl to interact with our cluster.
kubectl get pods -A
  • In the next section we will deploy into the running on the local kubernetes cluster.

Deploying a local microservice into the running kubernetes cluster

As I mentioned before, one of the advantages of using KIM in Rancher Desktop is the ability to run containers using kubectl without having to push/pull them into image registries, which not only saves the bandwidth of transferring them over all the time, but also it saves lots of development time.

Let’s have a look at it:

  • Let’s assume that I am developing some microservices and I want to test my latest version 0.1 in my local Kubernetes cluster, building with KIM.

NOTE: Normally, this would be some sort of CI/CD pipeline, but let’s assume manual work for now.

kim build -t carlosimage:0.1 .
  • Let’s make sure my image is in there:
kim images
  • Now, simply, let’s run it in Kubernetes, without needing to push/pull it into any image registry:
kubectl run carlosimage –image carlosimage:0.1
  • Since I don’t have to download it, within a few seconds, it will be up and running:
kubectl get pods -o wide
  • Now, just to prove that our microservice is up and running, let’s connect into it and run a curl command:
kubectl exec carlosimage — curl localhost:3000

Although a bit ugly, the answer should be the HTTP Hello World message back:

Isn’t it great? We were able to build, deploy and test our microservice using containerd, without having to learn anything new, just reusing our previous knowledge on Docker and Kubernetes. All locally from our local environment.

Last thing that I forgot to mention is that you might have other clusters configured locally on your laptop. Just, as you can do with Docker Desktop, you can go into the Rancher Desktop icon and simply switch contexts:

Congratulations!!!I hope you found this blog useful. I will keep publishing more topics around Kubernetes and Cloud Native, so stay tuned.

If you have any question or comment, feel free to contact me directly at

Thanks for your time.

Published by Carlos Rodriguez Iturria

To me, it’s all about being useful and adding value… If you want to connect with me, reach me at LinkedIn – That’s the best way that I have found to be responsive… (I hate emails).

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: