Provision a K3S - How to

On this page you will learn how to setup an edge system with K3S using the cluster installation tools in the Kelvin UI.

If you want Kelvin to install the Kubernetes cluster directly and handle all the management of the cluster, you can choose the K3S option.

For this option you only need to have Ubuntu Server to start the installation process.

This is an effortless, all-encompassing solution for clients indifferent to the Kubernetes flavor used and want to only focus on simplicity and minimal management requirements.

For all other options, you will need to install and manage the Kubernetes cluster yourself. Kelvin will only install and maintain the Kelvin-specific management pods on the existing Kubernetes cluster.

K3S

K3s is a lightweight, fully compliant Kubernetes distribution that includes a range of features such as local storage provider, service load balancer, Helm and Traefik ingress controllers.

K3s is wrapped in a simple launcher, making it secure by default and easy to operate in lightweight environments.

It requires only a modern kernel and cgroup mounts as external dependencies, and all Kubernetes control plane components are encapsulated in a single binary, enabling K3s to automate complex cluster operations. It also packages required dependencies such as containerd, Flannel, CoreDNS, and host utilities.

Requirements

Before running the Kelvin provision script you need to make sure the following requirements are met;

Communications

The following ports will need to be open for outgoing and incoming communications;

Description	Port Type	Port No.
Server / Main Node	TCP	443
	TCP	5000
	TCP	6443
Worker Nodes	TCP	443
	TCP	5000
	UDP	8472
Kelvin SmartApp™ Services*	TCP/UDP	30000 - 32767

Kelvin SmartApp™ Services ports only need to be opened if there are plans to provide local services from deployed Kelvin SmartApp™.

Networking

If the cluster is more than 1 node, the Main Node must have a static IP address.

Hardware

Actual CPUs and RAM requirements will depend heavily on the requirements and quantity of Kelvin SmartApp™ that you want to deploy.

Resource hungry apps or deploying tens or hundreds of Kelvin SmartApp™ will require more resources.

For physical hardware and assuming each node is a computer, the minimum requirements for each computer will be;

It is strongly recommended to use SSD disks.

Processor	Min CPU Cores	Min RAM	Min HDD
x86_64	2	4 GB	25 GB
arm64	2	2 GB	25 GB

For cloud based clusters, the virtual requirements are;

Deployment Size	No of Nodes	Min No of VCPUS	Min Amount of RAM
Small	1	2	4
Medium	2 - 10	4	8
Large	11 - 100	8	16

Limitations/ Fixed Design

When deciding your hardware and infrastructure requirements, it is also important to keep the following limitations in mind.

Cluster

For each cluster there are some limitations and consideration;

Each node can hold a maximum of 110 pods.
In each cluster, 16 pods are reserved for core system Kelvin SmartApps™.
Core system Kelvin SmartApps™ will take 2GB of space.
Cluster and Node pod reserved CIDR: 10.42.0.0/16
Node Service CIDR: 10.43.0.0/24

Installation

The installation process is very simple and you can have your new Kelvin Cluster cluster up and running within ten minutes depending on your internet speed.

Install OS

To start you need to install a compatible operating system onto your computer/server.

We recommend using Ubuntu Server version 18.04 or newer. We also strongly advise that you use only long term support versions of Ubuntu server which are released in April every two years. and has security support for 5 years minimum with options to extend it up to ten years with an ESM contract.

At a minimum you only need to install a command line server without a graphic user interface.

You can download Ubuntu Server here.

Install Cluster

This will install Kubernetes and setup the Main Node into a one Node cluster and register the Cluster with the Kelvin Cloud.

After the Cluster has been successfully setup, you can then add additional Nodes to the Cluster.

Video TutorialKelvin UIKelvin APIKelvin API Client (Python)

Watch this tutorial performed in real time in less than 3 minutes.

Let's dive in and show you how fast and easy the setup can be by first logging into the Kelvin Platform and going step by through the process.

1. Register Cluster in the Cloud

In the Kelvin UI, first head over to the Clusters section under orchestration and click on the register cluster button.

In the popup, assign the new cluster a recognizable display name. The name id will be automatically created from your display name. It can usually be left unchanged.

As you scroll down, you'll see two cluster options to choose from.

Advanced users can select the kubernetes option if you want to use your own cluster setup. This can also be used on clusters that already are in operation.

For this tutorial we will select the K3S option. With this option, no cluster knowledge is required as Kelvin will handle the installation and ongoing maintenance transparently.

Click Register.

You will then be provided with a script that needs to be executed on the edge system.

If you are using SSH to manage the edge system remotely, copy this script to your clipboard.

If you're accessing the edge system directly, note down the script.

Next click the close button. The cluster is now registered in the Cloud and you can see it is pending registration.

2. Install Cluster on the Edge System

In the terminal of the edge system, you can enter the script provided earlier.

Since we have SSH'd into the edge system we can simply paste the script from the clipboard.

Next, enter the edge computer's password to gain sudo rights. Note that this is not your Kelvin Platform password.

The rest of the process, including installing the cluster and connecting it to the Kelvin platform, is fully automated. Sit back and enjoy a cup of coffee. It should only take about a minute, so we'll skip ahead.

Once completed, you can go back to the Kelvin UI and see the cluster is up and running.

Congratulations, you have setup your first edge cluster. Now, let's stop the clock.

If you have followed this in the video tutorial you will see have created a cluster in this tutorial with two simple steps in under three minutes.

curl -X "POST" \
"https://<url.kelvin.ai>/api/v4/orchestration/clusters/create" \
-H "Authorization: Bearer <Your Current Token>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
    "name": "doc-demo-cluster-k3s",
    "title": "Doc Demo Cluster K3S",
    "type": "k3s"
}'

The response will look something like this;

{
   "name":"doc-demo-cluster-k3s",
   "title":"Doc Demo Cluster K3S",
   "type":"k3s",
   "ready":false,
   "status":"pending_provision",
   "last_seen":null,
   "sync_scrape_interval":120,
   "manifests_scrape_interval":130,
   "manifests_scrape_enabled":false,
   "version":{
      "k8s_version":"",
      "kelvin_version":""
   },
   "created":"2024-05-23T14:02:03.502407Z",
   "updated":"2024-05-23T14:02:03.502407Z",
   "service_account_token":"bm9kZS1jbGllbnQtZG9jLWRlbW8tY2x1c3Rlci1rM3M6WUw3Rk96UkV1OVRBYWlvbGNEODRCUXhtcnE1NjFaM1g=",
   "provision_script":"bash \u003c(curl -sfS https://<url.kelvin.ai>/provision) --service-account bm9kZS1jbGllbnQtZG9jLWRlbW8tY2x1c3Rlci1rM3M6WUw3Rk96UkV1OVRBYWlvbGNEODRCUXhtcnE1NjFaM1g=",
   "join_script":"bash \u003c(curl -sfS https://<url.kelvin.ai>/provision) --join --ip \u003cmain_cluster_node_ip_address\u003e --token ",
   "telemetry_scrape_interval":110,
   "telemetry_enabled":false,
   "telemetry_buffer_size":10,
   "forward_logs_enabled":false,
   "forward_logs_buffer_size":10,
   "upgrade_status":{
      "state":"idle",
      "message":""
   },
   "upgrade_pre_download":false,
   "upgrade_instantly_apply":true
}

Use the value from the key provision_script which will look something like this;

bash <(curl -sfS https://<url.kelvin.ai>/provision) --service-account bm9kZS1jbGllbnQtZG9jdW1lbnRhdGlvbi1jbHVzdGVyOmFuRnlZZFJ2WGlHSk83cTFaSFE4OW01QTNEMElsNFVN

Copy and type this into the Ubuntu server terminal. The whole setup procedure is then setup automatically.

Optionally you can ignore the --service-account parameter. When the installation is started you will be asked to give your username and password and the name of the Cluster to install.

bash <(curl -sfS https://<url.kelvin.ai>/provision)

Wait a couple of minutes for the script to finish.

When the script finishes, you will see the following output:

Congratulations, after a few minutes depending on your Internet speed your new cluster is ready for use.

from kelvin.api.client import Client

# Login
client = Client(config={"url": "https://<url.kelvin.ai>", "username": "<your_username>"})
client.login(password="<your_password>")

# Set or Update the Default Cluster in an Instance
response = client.orchestration.create_orchestration_clusters(data={
    "name": "doc-demo-cluster-k3s",
    "title": "Doc Demo Cluster K3S",
    "type": "k3s"
    })

print(f'The new cluster "{response.title}" is now registered in Kelvin, run this provision script in your edge computer - "{response.provision_script}"')

You will see an output like this;

The new cluster "Doc Demo Cluster K3S" is now registered in Kelvin, run this provision script in your edge computer - "bash <(curl -sfS https://<url.kelvin.ai>/provision) --service-account bm9kZS1jbGllbnQtZGVtby1jbHVzdGVyLWszczpYdlpZTEQwc2JlU202S2c1ZDk0YzJvbGpQaFIzRjFFQQ=="

Copy and type the provision script into the Ubuntu server terminal of your edge computer. The whole K3s setup procedure is then installed and configured automatically.

Optionally you can ignore the --service-account parameter. When the installation is started you will be asked to give your username and password and the name of the Cluster to install.

bash <(curl -sfS https://<url.kelvin.ai>/provision)

Wait a couple of minutes for the script to finish.

When the script finishes, you will see the following output:

Congratulations, after a few minutes depending on your Internet speed your new cluster is ready for use.