Installing with k0sctl

This tutorial is based on k0sctl tool and it’s targeted for creating a multi-node cluster for remote hosts. It describes an install method, which is automatic and easily repeatable. This is recommended for production clusters and the automatic upgrade requires using this install method. The automatic upgrade process is also described in this tutorial.

k0sctl is a command-line tool for bootstrapping and managing k0s clusters. k0sctl connects to the provided hosts using SSH and gathers information about the hosts. Based on the findings it proceeds to configure the hosts, deploys k0s and connects the k0s nodes together to form a cluster.

k0sctl deployment

Prerequisites

k0sctl can be executed on Linux, MacOS and Windows. See more details from the k0sctl github repository. For hosts running k0s, see the System Requirements.

Installation steps

1. Install k0sctl tool

k0sctl is a single binary and the installation and download instructions can be found in the k0sctl github repository.

2. Configure the cluster

First create a k0sctl configuration file:

  1. $ k0sctl init > k0sctl.yaml

A k0sctl.yaml file will be created in the current directory:

  1. apiVersion: k0sctl.k0sproject.io/v1beta1
  2. kind: Cluster
  3. metadata:
  4.   name: k0s-cluster
  5. spec:
  6.   hosts:
  7.   - role: controller
  8.     ssh:
  9.       address: 10.0.0.1 # replace with the controller's IP address
  10.       user: root
  11.       keyPath: ~/.ssh/id_rsa
  12.   - role: worker
  13.     ssh:
  14.       address: 10.0.0.2 # replace with the worker's IP address
  15.       user: root
  16.       keyPath: ~/.ssh/id_rsa

As a mandatory step, each host must be given a valid IP address (which is reachable by k0sctl) and the connection details for an SSH connection. k0sctl configuration specifications can be found in k0sctl documentation.

3. Deploy the cluster

Next step is to run k0sctl apply to perform the cluster deployment:

  1. $ k0sctl apply --config k0sctl.yaml 
  3. ⠀⣿⣿⡇⠀⠀⢀⣴⣾⣿⠟⠁⢸⣿⣿⣿⣿⣿⣿⣿⡿⠛⠁⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀█████████ █████████ ███
  4. ⠀⣿⣿⡇⣠⣶⣿⡿⠋⠀⠀⠀⢸⣿⡇⠀⠀⠀⣠⠀⠀⢀⣠⡆⢸⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀███          ███    ███
  5. ⠀⣿⣿⣿⣿⣟⠋⠀⠀⠀⠀⠀⢸⣿⡇⠀⢰⣾⣿⠀⠀⣿⣿⡇⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀███          ███    ███
  6. ⠀⣿⣿⡏⠻⣿⣷⣤⡀⠀⠀⠀⠸⠛⠁⠀⠸⠋⠁⠀⠀⣿⣿⡇⠈⠉⠉⠉⠉⠉⠉⠉⠉⢹⣿⣿⠀███          ███    ███
  7. ⠀⣿⣿⡇⠀⠀⠙⢿⣿⣦⣀⠀⠀⠀⣠⣶⣶⣶⣶⣶⣶⣿⣿⡇⢰⣶⣶⣶⣶⣶⣶⣶⣶⣾⣿⣿⠀█████████    ███    ██████████
  9. INFO k0sctl 0.0.0 Copyright 2021, Mirantis Inc.   
  10. INFO Anonymized telemetry will be sent to Mirantis. 
  11. INFO By continuing to use k0sctl you agree to these terms: 
  12. INFO https://k0sproject.io/licenses/eula          
  13. INFO ==> Running phase: Connect to hosts 
  14. INFO [ssh] 10.0.0.1:22: connected              
  15. INFO [ssh] 10.0.0.2:22: connected              
  16. INFO ==> Running phase: Detect host operating systems 
  17. INFO [ssh] 10.0.0.1:22: is running Ubuntu 20.10 
  18. INFO [ssh] 10.0.0.2:22: is running Ubuntu 20.10 
  19. INFO ==> Running phase: Prepare hosts    
  20. INFO [ssh] 10.0.0.1:22: installing kubectl     
  21. INFO ==> Running phase: Gather host facts 
  22. INFO [ssh] 10.0.0.1:22: discovered 10.12.18.133 as private address 
  23. INFO ==> Running phase: Validate hosts   
  24. INFO ==> Running phase: Gather k0s facts 
  25. INFO ==> Running phase: Download K0s on the hosts 
  26. INFO [ssh] 10.0.0.2:22: downloading k0s 0.11.0 
  27. INFO [ssh] 10.0.0.1:22: downloading k0s 0.11.0 
  28. INFO ==> Running phase: Configure K0s    
  29. WARN [ssh] 10.0.0.1:22: generating default configuration 
  30. INFO [ssh] 10.0.0.1:22: validating configuration 
  31. INFO [ssh] 10.0.0.1:22: configuration was changed 
  32. INFO ==> Running phase: Initialize K0s Cluster 
  33. INFO [ssh] 10.0.0.1:22: installing k0s controller 
  34. INFO [ssh] 10.0.0.1:22: waiting for the k0s service to start 
  35. INFO [ssh] 10.0.0.1:22: waiting for kubernetes api to respond 
  36. INFO ==> Running phase: Install workers  
  37. INFO [ssh] 10.0.0.1:22: generating token       
  38. INFO [ssh] 10.0.0.2:22: writing join token     
  39. INFO [ssh] 10.0.0.2:22: installing k0s worker  
  40. INFO [ssh] 10.0.0.2:22: starting service       
  41. INFO [ssh] 10.0.0.2:22: waiting for node to become ready 
  42. INFO ==> Running phase: Disconnect from hosts 
  43. INFO ==> Finished in 2m2s                
  44. INFO k0s cluster version 0.11.0 is now installed  
  45. INFO Tip: To access the cluster you can now fetch the admin kubeconfig using: 
  46. INFO      k0sctl kubeconfig

And — presto! Your k0s cluster is up and running.

4. Access the cluster

To access your k0s cluster, you first need to get the kubeconfig. k0sctl does this for you like this:

  1. $ k0sctl kubeconfig > kubeconfig

Then you can access your cluster for example by using kubectl or LENS.

  1. $ kubectl get pods --kubeconfig kubeconfig -A
  2. NAMESPACE     NAME                                       READY   STATUS    RESTARTS   AGE
  3. kube-system   calico-kube-controllers-5f6546844f-w8x27   1/1     Running   0          3m50s
  4. kube-system   calico-node-vd7lx                          1/1     Running   0          3m44s
  5. kube-system   coredns-5c98d7d4d8-tmrwv                   1/1     Running   0          4m10s
  6. kube-system   konnectivity-agent-d9xv2                   1/1     Running   0          3m31s
  7. kube-system   kube-proxy-xp9r9                           1/1     Running   0          4m4s
  8. kube-system   metrics-server-6fbcd86f7b-5frtn            1/1     Running   0          3m51s

Upgrade a k0s cluster using k0sctl

There’s no dedicated upgrade sub-command in k0sctl, the configuration file describes the desired state of the cluster and when passed to k0sctl apply, it will perform a discovery of the current state and do what ever is needed to bring the cluster to the desired state, by for example performing an upgrade.

K0sctl cluster upgrade process

The following steps will be performed during a k0sctl cluster upgrade:

  1. Upgrade each controller one-by-one; As long as there’s multiple controllers configured there’s no downtime
  2. Upgrade workers in batches; 10% of the worker nodes are upgraded at a time
  3. Each worker is first drained allowing the workload to “move” to other nodes before the actual upgrade of the worker node components
  4. The process continues after we see the upgraded nodes back in “Ready” state
  5. Drain can be skipped with a —no-drain option

The desired cluster version can be configured In the k0sctl configuration by setting the value of spec.k0s.version:

  1. spec:
  2.   k0s:
  3.     version: 0.11.0

When a version has not been specified, k0sctl will check online for the latest version and default to using that.

  1. $ k0sctl apply
  2. ...
  3. ...
  4. INFO[0001] ==> Running phase: Upgrade controllers 
  5. INFO[0001] [ssh] 10.0.0.23:22: starting upgrade
  6. INFO[0001] [ssh] 10.0.0.23:22: Running with legacy service name, migrating... 
  7. INFO[0011] [ssh] 10.0.0.23:22: waiting for the k0s service to start 
  8. INFO[0016] ==> Running phase: Upgrade workers  
  9. INFO[0016] Upgrading 1 workers in parallel              
  10. INFO[0016] [ssh] 10.0.0.17:22: upgrade starting  
  11. INFO[0027] [ssh] 10.0.0.17:22: waiting for node to become ready again 
  12. INFO[0027] [ssh] 10.0.0.17:22: upgrade successful   
  13. INFO[0027] ==> Running phase: Disconnect from hosts 
  14. INFO[0027] ==> Finished in 27s                 
  15. INFO[0027] k0s cluster version 0.11.0 is now installed 
  16. INFO[0027] Tip: To access the cluster you can now fetch the admin kubeconfig using: 
  17. INFO[0027]      k0sctl kubeconfig

Known limitations

  • k0sctl will not perform any discovery of hosts, it only operates on the hosts listed in the provided configuration
  • k0sctl can currently only add more nodes to the cluster but cannot remove existing ones

Next Steps