K3sup – automated K3s Kubernetes cluster install

When working with Kubernetes clusters in the home lab and spinning up learning environments, automation is key to creating dependable lab environments and even “production” environments for home using Kubernetes clusters. If you are looking for a tool to automate the process of spinning up K3s Kubernetes cluster configuration deployments, K3sup is a great tool that allows easily doing this from a remote Linux host with SSH access to your nodes. Let’s see how.

What is K3s?

The K3s Kubernetes distribution from Rancher is a lightweight Kubernetes distribution built for IoT & Edge computing environments. It is engineered for high availability and is meant for production workloads.

K3s is packaged as a single binary of less than 50 MB, reducing the dependencies and steps needed to install and run Kubernetes. You can also run it on a Raspberry Pi cluster, as ARM4 and ARMv7 architectures are supported which are great for edge locations. It is a popular installable Kubernetes distributions for home lab and production setup.

You can also run K3s inside Docker containers using K3D to install and configure K3s in Docker. Check out my video on that topic below:

What is K3sup?

The K3sup utility is a light weight utility that uses SSH key access to install K3S cluster configuration deployments on Linux hosts as one or more agents. It uses the script provided by Rancher to install K3s to begin with on your own Kubernetes cluster. You can use your local or remote VM to connect to the K3s virtual machines.

Configure TLS for high availability

It also ensures it flags your hosts’ public IP address so that TLS can be appropriately configured. After deployment, K3sup grabs the kubeconfig file from the server and updates this to reflect the deployment so you can use this for connecting to your Kubernetes cluster. This default kubectl config is created when the cluster comes up. The cluster’s kubeconfig file allows connecting and interacting with Kubernetes from your workstation, laptop, or other tools.

Why use K3sup?

Does K3s do what you can do with the Bash shell? Yes, that is true. However, like Vagrant, Ansible, and other tools to produce repeatable results, K3sup provides many developers with the tools needed to develop against consistently deployed Kubernetes clusters.

Single server, multi master node, clustering mode, etc

You can deploy your master node and then join existing Linux hosts as worker nodes to your K3s cluster using the K3sup join command. You can also use K3sup to deploy a single server, single node configuration. You can set up the clustering mode.

You have additional configuration options:

• Optional extra argument

• Environment variable configuration

• Run from your local machine

• Merge config

• Install K3s on a remote computer

• Set the Kubeconfig context

K3s in HA mode using K3Sup install

You can use K3sup to add config to your K3s cluster in embedded HA mode with the embedded HA with embedded ETCD. You can use K3sup to install a K3s cluster in an embedded ETCD and then use a solution like Kube-VIP for bare metal Kubernetes clusters to have high availability with the Kubernetes API.

Kubernetes provides glue code to use a cloud providers load balancer for high availability to your Kubernetes cluster. However, you need to use something like Kube-VIP for bare metal solutions. It provides both an API and service load balancer.

K3Sup install process

The process of the K3sup install is straightforward. You just run the install script to install K3sup on your Linux workstation to a specific path:

curl -sLS https://get.k3sup.dev | sh

sudo install k3sup /usr/local/bin/

To look at the help for k3sup, use the following:

k3sup --help

Create a K3S cluster with K3Sup

Now, let’s use K3sup to create a new K3s cluster and see how this process works. First, we need to create and copy over SSH key config to the target server.

Create and copy over SSH key to target servers

There are a couple of simple commands needed to create and copy over the SSH key config to your target servers.

Generate the key

To generate the SSH key:

ssh-key-gen

Copy over the SSH key

To copy over the SSH key to your target servers:

ssh-copy-id <user>@<server IP>

Below, I have created the SSH keypair and I am copying over the SSH key to one of my target servers. This applies to a single-node or multi-master node configuration. Make sure the user you are using has sufficient privileges and in the right security group. This allows us to set up a passwordless authentication less sudo for performing the configuration.

Alternative port for connectivity

By default K3sup will use SSH port 22, but you can specify an alternative port with the parameter:

--ssh-port

Use K3Sup to create the K3S cluster on the master node

Now, let’s use K3Sup to create the K3S cluster. To create the K3s cluster using K3Sup, note the following elements:

• k3sup install ip

• k3sup server ip server_ip user

• k3s-channel stable – install a specific version

• cluster

• user

• local path or current working directory for kubeconfig file

• context

• node ip

• tls san subjects

• server – this tells K3s you want this to be a master node housing the etcd database

The command

k3sup install --ip 10.1.149.123 --tls-san 10.1.149.126 --cluster --user root --local-path ~/.kube/config --context k3s-ha --no-extras --k3s-extra-args "--flannel-iface=ens192 --node-ip 10.1.149.123"

K3Sup join additional nodes to the

To perform a K3s join of other nodes in the cluster, you need to alter the command just a bit from a cluster install to a cluster join.

The command

By default, it will install the additional node as additional worker nodes. We would need to specify the server flag to add this as another master node.

k3sup join --ip 10.1.149.125 --server-ip 10.1.149.123 --user root --k3s-extra-args "--flannel-iface=ens192 --node-ip 10.1.149.125"

Below is a view of running the command to join an additional node to the cluster. I will perform this operation on two nodes to have one master and two nodes.

Kubectl

After joining two other nodes, you can run the kubectl get nodes command tool to view your kubectl node configuration.

kubectl get nodes

Checking your Kubernetes cluster with Kubectl get node

It displays the normal name status roles age version columns with the information from your Kubernetes nodes.

K3sup FAQs:

What is K3sup? It is a robust command line tool to quickly spin up K3s clusters in your environment using a passwordless SSH connection with SSH keys. It makes creating K3s clusters easy. You can configure these as single node, multi-master node configuration, etc.

What is K3s? K3s is a lightweight Kubernetes distribution from Rancher that provides a production-ready Kubernetes release to run business-critical workloads. It is powerful enough for large environments but lightweight enough you can run it on Raspberry pi devices in edge locations.

What is Kubernetes? Kubernetes is a container orchestration tool that is the de facto standard for orchestrating and managing Kubernetes in the enterprise today.

Wrapping Up

Hopefully, this overview of using K3sup to automate your Kubernetes cluster installs using Rancher’s K3s will help any looking for a quick and easy developer tool for easily spinning up K3s clusters. It allows for a repeatable automated approach and works well with scripting.