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.

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.

cat /etc/os-release

Output:

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.

uname -a

Output:

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.

Ozeino 2.4GHz Wireless Gaming Headset for PC, Ps5, Ps4 – Lossless Audio USB & Type-C Ultra Stable Gaming Headphones with Flip Microphone, 40-Hr Battery Gamer Headset for Switch, Laptop, Mobile, Mac

(4256449)

$29.99 (as of June 15, 2025 21:44 GMT +00:00 – More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

Install k3s Server Node with k3OS

Start k3OS configurations using following command.

sudo os-config

Output:

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.

kubectl get nodes

Output:

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.

NETGEAR Nighthawk Tri-Band WiFi 7 Router (RS280S) – Security Features, BE9200 Wireless Speed (up to 9.2 Gbps) – Covers up to 2,500 sq. ft., 100 Devices – 2.5 Gig Internet Port – Includes 1-Year Armor

(38543)

$188.57 (as of June 15, 2025 19:33 GMT +00:00 – More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

Install k3s Agent Node with k3OS

Start k3OS configurations using following commands.

sudo os-config

Output:

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.

kubectl get nodes

Output:

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.

kubectl cluster-info

Output:

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.

kubectl run --generator=run-pod/v1 my-nginx --image=nginx --replicas=2 --port=80

Output:

pod/my-nginx created

Export nginx service.

kubectl expose deployment my-nginx --port=80 --type=LoadBalancer

Output:

service/my-nginx exposed

Check Kubernetes (K3s) services.

kubectl get services --watch

Output:

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: Certified Kubernetes Administrator (CKA) with Practice Tests from Mumshad Mannambeth, KodeKloud Training

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.

Struggling with Linux server management? I offer professional support to ensure your servers are secure, optimized, and always available. Visit my Fiverr profile to learn more!

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