Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

Posted November 14, 2023
Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

K3s is a production-ready and lightweight Kubernetes distribution. K3s has simplified setting up Kubernetes clusters on any machine, such as Ubuntu. So, dive into this guide and learn the step-by-step process of Installing and configuring K3s on Ubuntu 20.04 and 22.04 LTS.

In summary, you will cover the following major K3s Ubuntu configurations:

  • The step-by-step process provisions a single-node cluster on Ubuntu.
  • Deploying any application using Kubectl, K3s, and your Ubuntu server.
  • Managing your K3s Ubuntu resources.
  • Accessing K3s Ubuntu cluster with Kubernetes dashboard via a web browser.
  • Uninstall k3s (if needed).

Prerequisites

Installing K3s on Ubuntu 20.04|22.04 is a hands-on guide. So, ensure you have the following system requirements:

  • Ensure you have Ubuntu installed on the machine you intend to set up the k3s cluster.
  • The minimum system requirements for k3s installation is 1 vCPU (More for better performance), at least 1 GB RAM, and 20 GB of free disk space.
  • Have root access to your Ubuntu server to run K3s commands with sudo privileges.

Related:Guide To Running Production K3s Cluster On AWS EC2

Step 1: Update your System Packages

Before running K3s installation commands, ensure your Ubuntu server is up to date, and that installed packages are to their latest versions. Use the following command:

sudo apt update

Ubuntu will then apply changes needed to update the packages using the following command:

sudo apt upgrade -y

You can follow up with a reboot command on your machine to complete these update processes:

sudo reboot

Step 2: A Single-node K3S Cluster Installation Process using Ubuntu

Are you ready for the fun part? Let’s get K3s up and running using the following command:

curl -sfL https://get.k3s.io | sh -

Running the above command will automatically start and run a single-node K3S cluster as such:

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

You can indeed confirm if K3s is perfectly running using the following command:

sudo systemctl status k3s

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

Step 3: Verify the k3s cluster is running properly

To leave no doubts that k3s cluster is running properly, check the status of k3s services using the following commands:

kubectl get nodes
kubectl cluster-info
kubectl get pods -A

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

Step 3: Troubleshooting K3s Ubuntu Installation Errors (If Any)

If running the above commands gave you an error, then let’s solve it right away before checking the next step. The main error that will occur is as follows:

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

This means your server lacks permissions to access /etc/rancher/k3s/k3s.yaml file and contains K3s configurations.

To resolve the error, elevate permissions to this file using the following command:

sudo chmod 644 /etc/rancher/k3s/k3s.yaml

You might have to reboot your machine your machine here. Alternatively, you can reinstall K3s on Ubuntu and add K3S_KUBECONFIG_MODE with 644 permissions as follows:

curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s -

Now you can rerun K3s check status commands, and your cluster should be ready;

kubectl get nodes
kubectl cluster-info

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

If this didn’t work, check this Solving unable to read etc rancher k3s yaml K3S Error guide for further troubleshooting commands.

Step 4: Deploying Any Application Using Kubectl, K3s, And Your Ubuntu server

With your single-node K3s cluster ready, let’s deploy and run an application on K3s.

Your typical application deployment will use a .yml file containing deployment service and load balancer configurations.

In this demo, let’s run an NGINX server on K3s. In this case, I have created a deployment.yml file and add deployment, service, and Ingress to expose the application as follows:

Create your file as follows:

nano deployment.yml

Then add the following configurations and save your file:

# NGINX Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        # Container port where NGINX listens
        - containerPort: 80

# NGINX Service
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app: nginx
  name: nginx-service
spec:
  ports:
    - name: http
      port: 80
      protocol: TCP
      # Expose port 80 on the service
      targetPort: 80
  selector:
  # Link this service to pods with the label app=nginx
    app: nginx

# NGINX Ingress
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-ingress
spec:
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            # Redirect traffic to service on port 80
            backend:
              service:
                name: nginx-service
                port:
                  number: 80

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

Now, you will use kubectl to deploy the application. So run the following command:

kubectl apply -f deployment.yml

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

And if you run the following command, your app should be ready and exposed:

kubectl get svc nginx-service

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

To check if the installed K3s Ubuntu cluster is running your app correctly, open your server IP and confirm the app is running as expected:

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

If you are on a local machine, use curl and run the following command:

curl <Your-Ubuntu-System-IP-Address>:80

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

You have now successfully deployed your app t a K3s cluster.

Step 5: Accessing K3s Ubuntu Cluster with Kubernetes Dashboard via a Web Browser

To manage and monitor your cluster, you need to access a dashboard. I’m not a big fan of the Kubernetes dashboard. I love using K9s, and I recommend it as well.

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

If you are looking to use Kubernetes dashboard,

kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml

kubectl patch svc kubernetes-dashboard --type='json' -p '[{"op":"replace","path":"/spec/type","value":"NodePort"}]' -n kubernetes-dashboard

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

Confirm Kubernetes dashboard pods are running using the following command:

kubectl get pods -n kubernetes-dashboard
kubectl get svc -n kubernetes-dashboard

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

Create a new file kubernetes-dashboard.yml:

nano kubernetes-dashboard.yml

This file should contain the following configurations:

# ServiceAccount Definition
apiVersion: v1
kind: ServiceAccount
metadata:
  name: admin-user  # Name of the service account
  namespace: kube-system  # Namespace in which the service account exists

# ClusterRoleBinding Definition
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin-user  # Name of the cluster role binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin  # Name of the cluster role
subjects:
- kind: ServiceAccount
  name: admin-user  # Name of the service account
  namespace: kube-system  # Namespace in which the service account exists

Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

Apply the changes:

kubectl create -f kubernetes-dashboard.yml

Generate the access tokens:

kubectl -n kube-system create token admin-user

Finally, access your Kubernetes dashboard on https://<Ubuntu-IP-Address>:dashboardNodePort

Step 6: Managing k3s Services

Start/stop/restart k3s services using the command:

sudo systemctl start k3s
sudo systemctl stop k3s
sudo systemctl restart k3s

Step 7: Uninstall k3s (if needed)

To uninstall k3s, use the provided uninstall

/usr/local/bin/k3s-uninstall.sh

Conclusion

In this guide, you have comfortably learned all the steps you need to install and run K3s on 20.04|22.04 LTS step-by-step.

In summary, you learned:

  • The step-by-step process provisions a single-node cluster on Ubuntu.
  • Deploying any application using Kubectl, K3s, and your Ubuntu server.
  • Managing your K3s Ubuntu resources.
  • Accessing K3s Ubuntu cluster with Kubernetes dashboard via a web browser.
  • Uninstall k3s (if needed).
Install Single Node K3s on Ubuntu 20.04|22.04 Step-by-Step

Written By:

Joseph Chege