NEW! Dynamic Resource Balancer in Mirantis OpenStack for Kubernetes 24.2   |   Learn More

Download K0S - Zero-Friction Kubernetes

Deploy k0s — a lightweight Kubernetes distribution for any application, ideal for learners

k0s is a zero-friction Kubernetes distribution that runs on any Linux-based operating system. It’s great for learning Kubernetes or building high-performance projects on platforms from Raspberry Pis to bare metal datacenters. k0s is distributed as a single binary, installed on any node from the internet with one command, that works like a command-line application. You can call k0s from the command line to start a controller node (or controller+worker), then ask the controller for join tokens that can be used to start k0s on additional machines as controllers or workers, and join them to your cluster.

In this tutorial, we'll use k0s to create two different kinds of clusters:

  • A single node cluster (controller+worker)

  • A two-node cluster (separate controller and worker)

Note: The instructions below are for installing k0s manually. If you instead prefer to install k0s using the k0sctl utility, you can find instructions here.


  • A laptop or VM with internet access, configured for Kubernetes operations and development. If you haven’t already constructed this, our tutorial How to Build a Kubernetes Development Environment gives a complete recipe.

  • One or two (depending on whether you want to make a single-node or two-node k0s cluster) server VMs, connected to local network, network-accessible to your laptop (and if you're making a two-node cluster, to each another), and able to reach the internet. We recommend Ubuntu 22.04 LTS servers (or desktop installs) running on AWS or VirtualBox, though the instructions should work for VMs running a recent version of any popular Linux on any public or private cloud. If you’re not familiar with launching VMs on AWS or building VMs on VirtualBox, our tutorials Launching Virtual Machines on AWS and How to Create a Server on VirtualBox provide all the instructions.

  • Servers must be configured for passwordless sudo, and must have curl installed. Instructions for these configuration steps can be found in the tutorial How to Create a Server on VirtualBox.

  • Assuming you're not running DNS locally, it's helpful if you add your server IP addresses and hostnames to /etc/hosts on your management laptop, and on the target server(s) you're using. You should be able to SSH from your laptop to either target server using ssh you@hostname, and from each target server to the other.

  • Enable passwordless, keywise SSH by hostname from your laptop to target servers, and from one target server to the other in both directions, following instructions here. This will make life easier as you SSH around from one machine to the others.

Hardware Requirements for k0s nodes

  • 1 vCPU (2 vCPU recommended)

  • 1 GB of RAM (2 GB recommended)

  • .5 GB of free disk space for controller nodes. SSD is recommended.

  • 1.3 GB of free disk space for worker nodes. SSD is recommended.

  • 1.7 GB of free disk space for combined controller/worker nodes. SSD is recommended.

Step 1: Create target servers

Begin by creating your two target machine servers, ensuring they’re configured correctly, that you can SSH to them with your private key, and that your administrative user can issue sudo commands without a password. Also ensure that curl is installed on both machines.

Step 2: Install the k0s system

SSH to each target server and enter the command below. The script downloads the latest stable k0s binary, then installs it on your server.

curl -sSLf | sudo sh

What we're actually doing, here, is downloading the k0s binary and installing the k0s system on the host: including its CLI (accessed from the command line using the new 'k0s' command), k0s components, an appropriate version of kubectl, and other tools. Thereafter, we'll use the k0s command to configure, install, start/stop, generate join tokens, and manage k0s in various roles (e.g., controller, worker, or controller+worker). As we'll see below, you can also use the k0s kubectl command to work with the cluster from the command line of any node.

Step 3: Single-node k0s cluster

SSH to your target machine and use the k0s install command to install k0s as a controller+worker, as shown below. When installed this way, k0s sets itself up by default as a service when started for the first time -- so your controller will start automatically when this node boots.

sudo k0s install controller --enable-worker

The k0s install controller command can take an optional argument (--config) with the name of a configuration file. If this isn't supplied, k0s installs with a default configuration that it generates dynamically. You can look at the default configuration by issuing the command:

sudo k0s config create

... and save it in a file (e.g., k0s.yaml) for study and modification.

In this case, however, the default configuration should work fine.

Now start k0s with the command:

sudo k0s start

k0s installs by default as a service, so will restart automatically when this node boots.

In a minute or so, you can check cluster status:

sudo k0s status

You should see something like this:

Version: v1.29.3+k0s.0
Process ID: 2848
Role: controller
Workloads: true
SingleNode: false
Kube-api probing successful: true
Kube-api probing last error:

You can use k0s kubectl to see the worker node:

$ sudo k0s kubectl get nodes
new-ubuntu   Ready    <none>   17s   v1.29.3+k0s

And see the system and housekeeping pods running in the default system:

$ sudo k0s kubectl get pods --all-namespaces
NAMESPACE     NAME                              READY   STATUS    RESTARTS   AGE
kube-system   coredns-6cd46fb86c-qr5x4          1/1     Running   0          7m56s
kube-system   konnectivity-agent-pvrnm          1/1     Running   0          7m56s
kube-system   kube-proxy-f4w2m                  1/1     Running   0          7m56s
kube-system   kube-router-d796h                 1/1     Running   0          7m56s
kube-system   metrics-server-7556957bb7-nd5xw   1/1     Running   0          7m56s

Now you have a choice: skip down to where we show you how to access your single-node k0s cluster with Lens (and have more fun with it), or stop and reset this node and build a two-node cluster.

To stop and reset the node:

sudo k0s stop
sudo k0s reset

k0s will warn you that it's good practice to reboot your node at this point (to ensure that everything is reset). You can do this by entering:

sudo shutdown -r now

Step 4: (Two-node cluster) Start k0s as a controller

Now we'll make a two-node k0s cluster. Start by SSH'ing to your first node (or opening a terminal if you're working with a desktop OS) and enter the command:

sudo k0s install controller

Then start k0s as a controller by entering:

sudo k0s start

We'll wait a minute or so to let the controller spin up, then check its status by entering:

sudo k0s status

We should see something like this:

Version: v1.29.3+k0s.0
Process ID: 3871
Role: controller
Workloads: false
SingleNode: false

We can also use k0s kubectl to talk to the Kubernetes API directly -- though there's nothing much to see, yet:

sudo k0s kubectl get nodes

Because k0s runs controller components as bare functions, there are actually no nodes yet.

No resources found

Kubectl will report this correctly. To see a node, we'll need to add a worker.

Step 5: Get a worker join token and start your worker

You'll need to obtain a worker join token from your controller in order to start your worker (on your other target node) and join it to your cluster. The k0s CLI lets you do this very easily, saving the token in a file.

sudo k0s token create --role=worker > workertoken.txt

The resulting output (stored in workertoken.txt) is a long string that represents a KUBECONFIG, encoded using BASE64.

You can use various methods to grab the token file and copy it to your second target machine (i.e., your soon-to-be worker node). One way is with SCP:

scp workertoken.txt you@worker:.

... leaving the file workertoken.txt in the home directory of your account on the 'worker' server.

Step 6: Start k0s as a worker and join to your cluster

Now SSH to your worker (where you've already installed the k0s system) and enter:

sudo k0s install worker --token-file ./workertoken.txt

And finally:

sudo k0s start

Now exit and SSH back into your controller node, and check node status:

sudo k0s kubectl get nodes
my-worker   Ready    <none>   18m   v1.29.3+k0s

Now we have one worker node, noted under its hostname.

Step 7: Get your kubeconfig

You’re not always going to want to connect using the kubectl that comes with k0s, since that means logging into the controller node.

Better, you can retrieve a kubeconfig for your cluster that will work with kubectl installed on your laptop, or with Lens Desktop.

To do this, SSH to the controller (if you're not already there) and enter:

sudo k0s kubeconfig admin > my_config

k0s will save your cluster's administrative kubeconfig in that file. This can be retrieved various ways (e.g., using scp, cut-and-paste via a shared clipboard for desktop VMs, etc.) to your laptop.

Step 8: Connect to your k0s cluster using Lens

The simplest way to access a Kubernetes cluster is to use the Lens Kubernetes IDE. To access the cluster, first install Lens, then click in the upper left hand corner for the File menu, choose Add Cluster, and you'll see something like this:

Open your kubeconfig in an editor, select all, and paste to the dialog's edit area, then click Add Cluster. Your cluster will be added and appear as a new cluster in the Catalog. Double-click to connect, and you'll see something like this:

We're done! Have fun playing with your new k0s cluster! For more tutorials and documentation, please visit the k0s documentation.