How to setup k3s Cluster on k3OS

Learn how to setup K3s cluster on K3OS with our detailed guide. Follow step-by-step instructions, tips, and best practices for a seamless K3s installation and configuration. #centlinux #k3s #k3os

What is k3OS?

k3OS is a lightweight operating system, optimally designed to run Kubernetes (k8s) or more specifically Lightweight Kubernetes (k3s) clusters. The main aim of k3OS is to minimize operating system maintenance while running a Kubernetes (k3s) cluster. k3OS and k3s both are developed by Rancher Labs.

k3OS Kernel is forked from Ubuntu, while many of the user-space binaries comes from Alpine Linux, whereas some code is derived from LinuxKit. Additionally, the k3OS operating system is designed to be managed by kubectl once a cluster is bootstrapped. All aspects of the operating system of nodes will be managed by Kubernetes.

In this article, we will setup k3s cluster with k3OS operating system.

A very good and comprehensive reading reference is k3OS documentation.  But you should also read Kubernetes in Action (PAID LINK) by Manning Publications to have a good understanding of Kubernetes technology and its usage.

System Specification

We have provisioned two virtual machines with following specifications:

Install k3OS Operating System

We have downloaded iso of k3OS operating system from GitHub.

Attach the downloaded file k3os-amd64.iso in our virtual machine and start VM.

Select Run k3OS LiveCD or Installation and press <ENTER>.

The system then boot-up and reach at the login prompt. Login as rancher user without password.

After successful login, you may acquire a Bash shell. Then, use following command to set a password for rancher user. It will enable us to login to this machine using a ssh client.

Connect with this machine using ssh as rancher user.

login as: rancher
rancher@192.168.116.161's password:
Welcome to k3OS!

Refer to https://github.com/rancher/k3os for README and issues

By default mode of k3OS is to run a single node cluster. Use "kubectl"
to access it.  The node token in /var/lib/rancher/k3s/server/node-token
can be used to join agents to this server.


You can configure this system or install to disk using "sudo os-config"
k3os-24483 [~]$

Check the version of the k3OS operating system.

k3os-24483 [~]$ cat /etc/os-release
NAME="k3OS"
VERSION="k3OS v0.2.0-rc4"
ID=k3os
ID_LIKE=alpine
PRETTY_NAME="k3OS v0.2.0-rc4"
VERSION_ID="v0.2.0-rc4"
HOME_URL="https://k3os.io/"
SUPPORT_URL="https://k3os.io/"
BUG_REPORT_URL="https://github.com/rancher/k3os/issues"
ISO_URL="https://github.com/rancher/k3os/releases/download/v0.2.0-rc4/k3os.iso"

Check Linux Kernel version.

k3os-29512 [~]$ uname -a
Linux k3os-29512 4.15.0-47-generic #50 SMP Tue Apr 23 19:17:07 UTC 2019 x86_64 GNU/Linux

Repeat above steps on both machines.

Install k3s Server Node with k3OS

Start k3OS configurations using following command.

k3os-24483 [~]$ sudo os-config

Running k3OS configuration
Choose operation
1. Install to disk
2. Configure server or agent
Select Number []: 1

Choose the required operation and press <ENTER>.

Choose installation partition table type
1. gpt
2. msdos
Select Number [1]: 2

Choose installation partition table type according to your Hardware. If your system is UEFI based, then you must select gpt partition table type. If your system is BIOS based, then you must select msdos table partition type.

Press <ENTER>.

Config system with cloud-init file? [y/N]: N

k3OS operating system can be configured using a cloud-init file for automatic and fast provisioning of cloud instances. cloud-init is a separate topic and beyond the scope of this article, therefore, we are not using it now for the sake of simplicity. Once, you made your hand dirty with k3OS, then you can use cloud-init file.

Authorize GitHub users to SSH? [y/N]: N

If you are required to allow users to access GitHub using ssh from this machine then choose ‘y’ otherwise select ‘N’. If you choose ‘y’ then you have to provide a comma seperated list of authorized GitHub users.

Please enter password for [rancher]:

Set a password for rancher user.

Please enter password for [rancher]: ***
Confirm password for [rancher]: ***
chpasswd: password for 'rancher' changed
Run as server or agent?
1. server
2. agent
Select Number [1]: 1

Choose the role of this node and press <ENTER>.

Token or cluster secret (optional): karachi

Provide a cluster secret and Press <ENTER>. We will need this cluster secret, when joining a new node to our Lightweight Kubernetes (k3s) cluster.

k3OS then install and configure itself on our machine.

Check the current nodes in Kubernetes cluster.

k3os-24483 [~]$ kubectl get nodes
NAME         STATUS   ROLES    AGE     VERSION
k3os-24483   Ready    <none>   3m44s   v1.14.1-k3s.4

We have successfully installed k3OS and configured a Lightweight Kubernetes (k3s) Server node.

Install k3s Agent Node with k3OS

Start k3OS configurations using following commands.

k3os-13179 [~]$ sudo os-config

Running k3OS configuration
Choose operation
1. Install to disk
2. Configure server or agent
Select Number []: 1

Choose an operation and press <ENTER>.

Choose installation partition table type
1. gpt
2. msdos
Select Number [1]: 2

Choose installation partition table type and press <ENTER>.

Config system with cloud-init file? [y/N]: N

We are not using a cloud-init file, therefore, choose ‘N’ and press <ENTER>.

Authorize GitHub users to SSH? [y/N]: N

If you want users to access GiHub from this machine then press ‘y’ otherwise ‘N’. Press <ENTER>.

Please enter password for [rancher]: ***
Confirm password for [rancher]: ***
chpasswd: password for 'rancher' changed

Set a password for rancher user.

Run as server or agent?
1. server
2. agent
Select Number [1]: 2

We are configuring this machine as an Agent node, therefore, select option ‘2’ and press <ENTER>.

URL of server: https://192.168.116.163:6443
Token or cluster secret: karachi

Provide URL of Lightweight Kubernetes (k3s) Server and the cluster secret.

k3OS is then install & configure itself on this machine.

Check nodes status.

k3os-24483 [~]$ kubectl get nodes
NAME         STATUS   ROLES    AGE   VERSION
k3os-14464   Ready    <none>   35s   v1.14.1-k3s.4
k3os-24483   Ready    <none>   15m   v1.14.1-k3s.4

Check cluster status.

k3os-24483 [~]$ kubectl cluster-info
Kubernetes master is running at https://localhost:6443
CoreDNS is running at https://localhost:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Test Lightweight Kubernetes (k3s) cluster

To test our Kubernetes cluster, create a simple nginx web server.

k3os-24483 [~]$ kubectl run --generator=run-pod/v1 my-nginx --image=nginx --replicas=2 --port=80
pod/my-nginx created

Export nginx service.

k3os-24483 [~]$ kubectl expose deployment my-nginx --port=80 --type=LoadBalancer
service/my-nginx exposed

Check Kubernetes (K3s) services.

k3os-24483 [~]$ kubectl get services --watch
NAME         TYPE           CLUSTER-IP      EXTERNAL-IP       PORT(S)        AGE
kubernetes   ClusterIP      10.43.0.1       <none>            443/TCP        36m
my-nginx     LoadBalancer   10.43.231.232   192.168.116.164   80:30692/TCP   101s

Browse URL http://192.168.116.164 in a client’s browser.

Read Also: k3OS Network Configuration

Recommended Training for You: Starting With K3S (Lightweight Kubernetes) and MicroOS

Final Thoughts

Setting up a K3s cluster on K3OS can be a rewarding but challenging process. This guide is designed to provide you with clear, step-by-step instructions to ensure a successful setup. Whether you’re a beginner or an experienced user, following these steps will help you get your cluster up and running smoothly.

If you need further assistance or prefer a professional to handle the setup for you, I offer specialized services on Fiverr. From initial setup to advanced configurations, I can help you achieve a perfect K3s cluster on K3OS. Visit my Fiverr profile to learn more about my services and how I can assist you.

Thank you for reading, and best of luck with your K3s cluster setup!