EN

Applications

Install Kubernetes with K3s

Install K3s on Debian or Ubuntu, use kubectl, deploy a first application, add a node and secure the cluster ports.

7 min read, updated on 18 November 2026

On this page

Your values

Enter them once and the commands in this guide update.

K3s is a lightweight, certified Kubernetes distribution shipped as a single binary. It suits a VPS or a dedicated server well: it bundles kubectl, the Traefik Ingress controller, a simple load balancer and local storage.

This guide takes you from installation to a two-node cluster, on Debian 12/13 or Ubuntu 22.04/24.04:

  1. install the server node;
  2. use kubectl without exposing the API;
  3. deploy a first application;
  4. add an agent node;
  5. update and back up the cluster.

Order a Server

To host your cluster, HostMyServers offers several options:

Prerequisites

Role Minimum CPU Minimum RAM
Server 2 cores 2 GB
Agent 1 core 512 MB

These values, taken from the K3s documentation, do not include the resources your applications need.

You also need:

  • SSH access with a user that has sudo;
  • a different hostname on each node;
  • an IP address reachable by the other nodes, usually the public IP address;
  • the WireGuard kernel module if your nodes communicate over the Internet.

Check that WireGuard is present on each node:

Terminal
sudo modprobe wireguard && lsmod | grep wireguard

Ports

Port Protocol Source Usage
22 TCP Your computer SSH and tunnel to the API
6443 TCP Agents Kubernetes API and K3s supervisor
10250 TCP All nodes Kubelet metrics and API
51820 UDP All nodes Flannel WireGuard over IPv4
51821 UDP All nodes Flannel WireGuard over IPv6, if used
80, 443 TCP Internet Applications published by Traefik

Prepare the server

Terminal
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufw

The K3s documentation recommends disabling UFW, but a server exposed to the Internet should stay filtered. If you keep UFW, as here, K3s's internal networks must be allowed. Replace 22 if you use a different SSH port:

Terminal
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable

10.42.0.0/16 is the default pod network and 10.43.0.0/16 the default service network.

Install the server node

Prepare the configuration before installing. This way the cluster network is encrypted from the start, which lets you add a node over the Internet later.

Terminal
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yaml
YAML
node-external-ip: YOUR_SERVER_IP
flannel-backend: wireguard-native
flannel-external-ip: true
tls-san:
  - YOUR_SERVER_IP

Then install K3s with the official script, which follows the stable channel by default:

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

Check the service and the node. It may take a minute for the node to reach the Ready state:

Terminal
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A

Use kubectl

The /etc/rancher/k3s/k3s.yaml file gives full administrator access to the cluster and is readable only by root. Do not make it world-readable. Create a personal copy instead:

Terminal
mkdir -p ~/.kube
install -m 600 /dev/null ~/.kube/config
sudo k3s kubectl config view --raw > ~/.kube/config
echo 'export KUBECONFIG="$HOME/.kube/config"' >> ~/.bashrc
export KUBECONFIG="$HOME/.kube/config"
kubectl get nodes

Manage the cluster from your computer

The SSH tunnel avoids opening port 6443 to your computer. Install kubectl on your machine, then copy the configuration:

Terminal
mkdir -p ~/.kube
scp YOUR_USER@YOUR_SERVER_IP:.kube/config ~/.kube/k3s-hms
chmod 600 ~/.kube/k3s-hms
ssh -N -L 6443:127.0.0.1:6443 YOUR_USER@YOUR_SERVER_IP

Leave this tunnel open and, in another terminal:

Terminal
export KUBECONFIG=~/.kube/k3s-hms
kubectl get nodes

K3s renews the certificates in its admin file at every start. If your copy stops working, copy it again.

Deploy a first application

Create a manifest:

Terminal
nano demo.yaml
YAML
apiVersion: v1
kind: Namespace
metadata:
  name: demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:stable-alpine
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 50m
              memory: 32Mi
            limits:
              memory: 128Mi
---
apiVersion: v1
kind: Service
metadata:
  name: web
  namespace: demo
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: demo
spec:
  ingressClassName: traefik
  rules:
    - host: demo.your-domain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

Apply it and follow the rollout:

Terminal
kubectl apply -f demo.yaml
kubectl -n demo rollout status deployment/web
kubectl -n demo get pods,svc,ingress

Test the application from your own computer, even if DNS is not configured yet:

Terminal
curl -H 'Host: demo.your-domain.com' http://YOUR_SERVER_IP/

You should get the Nginx welcome page.

Delete the example when you no longer need it:

Terminal
kubectl delete namespace demo

Add an agent node

In this section, AGENT_IP is the IP address of the new node.

Open the traffic between nodes

On the server:

Terminal
sudo ufw allow from AGENT_IP to any port 6443 proto tcp
sudo ufw allow from AGENT_IP to any port 10250 proto tcp
sudo ufw allow from AGENT_IP to any port 51820 proto udp

On the agent:

Terminal
sudo apt update
sudo apt install -y curl ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw allow from YOUR_SERVER_IP to any port 10250 proto tcp
sudo ufw allow from YOUR_SERVER_IP to any port 51820 proto udp
sudo ufw enable

Ports 80 and 443 are needed on the agent because Traefik can be published on every node. With more than two nodes, open ports 10250/TCP and 51820/UDP between all nodes.

Join the cluster

On the server, display the token:

Terminal
sudo cat /var/lib/rancher/k3s/server/node-token

On the agent, set its external address, then start the installation. The read command waits for you to paste the token, without displaying it or saving it in your history:

Terminal
sudo mkdir -p /etc/rancher/k3s
echo 'node-external-ip: AGENT_IP' | sudo tee /etc/rancher/k3s/config.yaml
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://YOUR_SERVER_IP:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN
sudo systemctl status k3s-agent --no-pager

On the server, the new node must appear in the Ready state:

Terminal
kubectl get nodes -o wide

Update K3s

Back up the cluster first and read the release notes. Update the servers first, one at a time, then the agents, without skipping a Kubernetes minor version.

On the server, run the script again. The config.yaml configuration is kept:

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

On each agent, pass the same variables again:

Terminal
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://YOUR_SERVER_IP:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN

If your cluster is several minor versions behind, upgrade in steps using the matching channel, for example:

Terminal
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=v1.36 sh -

Then check the versions with kubectl get nodes.

Back up and restore

With SQLite, back up the database and the server token: without that token, the backup is unusable. Stopping K3s guarantees a consistent copy and does not stop containers that are already running.

Terminal
sudo systemctl stop k3s
sudo tar -czpf "/root/k3s-$(date +%F).tar.gz" /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/token /etc/rancher/k3s/config.yaml
sudo systemctl start k3s
sudo chmod 600 /root/k3s-*.tar.gz

Volumes created by local storage are in /var/lib/rancher/k3s/storage. Back them up too, ideally with each application's own tools, for example a database export. Also keep your manifests in a private Git repository.

To restore the database on the server:

Terminal
sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo tar -xzpf /root/k3s-YYYY-MM-DD.tar.gz -C /
sudo systemctl start k3s
kubectl get nodes

Troubleshooting

Unable to read /etc/rancher/k3s/k3s.yaml

Your user cannot access the admin file. Go back to the Use kubectl section and check echo $KUBECONFIG. Avoid making this file world-readable with --write-kubeconfig-mode 644.

The k3s service does not start

Terminal
sudo journalctl -u k3s -n 80 --no-pager
sudo k3s check-config

If the logs mention WireGuard, check sudo modprobe wireguard. When the module is unavailable on a single-node cluster, remove flannel-backend and flannel-external-ip from config.yaml before reinstalling. Do not replace WireGuard with VXLAN between nodes connected over the Internet.

The agent does not join the cluster

Terminal
sudo journalctl -u k3s-agent -n 80 --no-pager
curl -vk -m 5 https://YOUR_SERVER_IP:6443/ping
  • connection refused or timeout: check UFW and the K3S_URL address.
  • Invalid token: copy the contents of node-token again.
  • Node password rejected, duplicate hostname: another node has the same name, or this node was already registered. Change the hostname, or delete the old node with kubectl delete node NODE_NAME.

A node stays in the NotReady state

Terminal
kubectl describe node NODE_NAME
ip link show flannel-wg

Check ports 10250/TCP and 51820/UDP between the nodes, as well as the node-external-ip values.

A pod stays in Pending or ImagePullBackOff

Terminal
kubectl -n demo describe pod POD_NAME
kubectl -n demo logs POD_NAME

Pending often signals a lack of CPU or memory. ImagePullBackOff indicates an incorrect image name, registry access denied or a pull rate limit.

The Ingress returns 404 or ports 80/443 do not respond

Terminal
kubectl -n kube-system get pods,svc | grep -E 'traefik|svclb'
sudo ss -tlnp | grep -E ':(80|443)\b'

A 404 usually means the Host header does not match the Ingress host field. If the svclb pods stay Pending, a system service such as Nginx or Apache is probably already using ports 80 and 443.

Uninstall K3s

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

On an agent:

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

Going further

To store your container images, see the Install Harbor guide. To automate the preparation of your nodes, see Automate Your Servers with Ansible.

References