Supercharge your cloud strategy with these curated resources.  Dive In

K0s – Deploy with k0sctl

Deploy k0s — a lightweight Kubernetes distribution — using the community-maintained k0sctl utility

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. In this tutorial, we’ll learn to deploy k0s using the community-provided k0sctl application, which runs from the command line on Linux, Mac, and Windows.


  • 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 for setting up a Linux desktop with Ubuntu and installing basic tools.

  • Two server VMs, connected to the same local network, accessible via public or private IP addresses, and able to reach the internet, on which to install a k0s manager and a k0s worker node. We recommend Ubuntu 18.04 LTS servers running on AWS or VirtualBox, though the instructions should work for VMs running 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.

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: Download k0sctl

Fill out the form below and submit to obtain a link, then visit the link to download and install the latest version of k0sctl in a form appropriate for the machine you intend to use, to manage deployment. It can be helpful to add the k0sctl binary to your execution path, so you can call it from any directory.

Download and install k0sctl

Step 3: Create a template k0sctl.yaml file

k0sctl, like Mirantis Launchpad, uses a single YAML template file to declaratively describe the cluster you want to deploy. Once deployed, changes to this file can be applied to the cluster to converge it on a new state. The process is idempotent, but not non-disruptive to workloads.

k0sctl has a convenience command that helps you generate and save a basic k0sctl template file, easily adjusted to include specifics about your cluster. To generate this template, enter:

k0sctl init > k0sctl.yaml

Step 4: Modify the k0sctl.yaml file

Issuing the above command creates a template file similar to what’s shown below:

kind: Cluster
  name: k0s-cluster
  - ssh:
      address:                 # change this to your controller node's FQDN or IP
      user: root                        # change this to your admin username (sudo-enabled), e.g., "ubuntu"
      port: 22
      keyPath: /home/john/.ssh/id_rsa   # change this to point to the private keyfile that works on your target machines
    role: controller
  - ssh:
      address:                 # change this to your worker node's FQDN or IP
      user: root                        # change this to your admin username (sudo-enabled), e.g., "ubuntu"
      port: 22
      keyPath: /home/john/.ssh/id_rsa   # change this to point to the private keyfile that works on your target machines
    role: worker
    version: 1.21.0+k0s.0

The template file is already set up to create a two-node k0s cluster with a controller and a worker on separate machines. But three things (at least) will need to change:

  • First, you’ll need to provide the (private or public) IP addresses or FQDNs of the hosts you want to use to deploy your controller and worker, replacing the default IP addresses.

  • Second, you’ll probably need to change the username k0sctl will use to log into your hosts. For Ubuntu servers started on AWS, this is set by default to ‘ubuntu.’

  • Finally, you’ll need to point k0sctl to the private key that lets you log into these hosts. By default, k0sctl assumes this file is called id_rsa and is stored in your home directory’s .ssh folder (as is conventionally the case).

Step 5: Apply your template

Now you can apply your template to tell k0sctl to deploy your cluster.

k0sctl apply --config k0sctl.yaml

If everything is in order, k0sctl will begin logging progress, something like this:

./k0sctl apply --config k0sctl.yaml

⠀⣿⣿⡇⠀⠀⢀⣴⣾⣿⠟⠁⢸⣿⣿⣿⣿⣿⣿⣿⡿⠛⠁⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀█████████ █████████ ███
⠀⣿⣿⡇⣠⣶⣿⡿⠋⠀⠀⠀⢸⣿⡇⠀⠀⠀⣠⠀⠀⢀⣠⡆⢸⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀███          ███    ███
⠀⣿⣿⣿⣿⣟⠋⠀⠀⠀⠀⠀⢸⣿⡇⠀⢰⣾⣿⠀⠀⣿⣿⡇⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀███          ███    ███
⠀⣿⣿⡏⠻⣿⣷⣤⡀⠀⠀⠀⠸⠛⠁⠀⠸⠋⠁⠀⠀⣿⣿⡇⠈⠉⠉⠉⠉⠉⠉⠉⠉⢹⣿⣿⠀███          ███    ███
⠀⣿⣿⡇⠀⠀⠙⢿⣿⣦⣀⠀⠀⠀⣠⣶⣶⣶⣶⣶⣶⣿⣿⡇⢰⣶⣶⣶⣶⣶⣶⣶⣶⣾⣿⣿⠀█████████    ███    ██████████

k0sctl v0.7.0 Copyright 2021, k0sctl authors.
Anonymized telemetry of usage will be sent to the authors.
By continuing to use k0sctl you agree to these terms:
INFO ==> Running phase: Connect to hosts 
INFO [ssh] connected             
INFO [ssh] connected             
INFO ==> Running phase: Detect host operating systems 
INFO [ssh] is running Ubuntu 18.04.5 LTS 
INFO [ssh] is running Ubuntu 18.04.5 LTS

If successful, the process will conclude like this:

INFO ==> Finished in 4m16s               
INFO k0s cluster version 0.13.1 is now installed  
INFO Tip: To access the cluster you can now fetch the admin kubeconfig using: 
INFO      k0sctl kubeconfig

Step 6: Access the cluster with Lens

Once your cluster is created, accessing it with Lens is easy. Just enter the suggested command to download your kubeconfig:

k0sctl kubeconfig

Then install Lens (if necessary) using our download tutorial and add the kubeconfig for your new cluster to Lens as follows:

Click the add cluster button along the left-hand side of the window:

Select the KUBECONFIG file.

Finally, click Add Cluster.

You are now ready to work with your new k0s cluster.