Install Kubernetes with K3s
Install K3s on Debian or Ubuntu, use kubectl, deploy a first application, add a node and secure the cluster ports.
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:
- install the server node;
- use
kubectlwithout exposing the API; - deploy a first application;
- add an agent node;
- 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:
sudo modprobe wireguard && lsmod | grep wireguardPorts
| 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
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufwThe 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:
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 enable10.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.
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yamlnode-external-ip: YOUR_SERVER_IP
flannel-backend: wireguard-native
flannel-external-ip: true
tls-san:
- YOUR_SERVER_IPThen install K3s with the official script, which follows the stable channel by default:
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:
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -AUse 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:
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 nodesManage the cluster from your computer
The SSH tunnel avoids opening port 6443 to your computer. Install kubectl on your machine, then copy the configuration:
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_IPLeave this tunnel open and, in another terminal:
export KUBECONFIG=~/.kube/k3s-hms
kubectl get nodesK3s 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:
nano demo.yamlapiVersion: 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: 80Apply it and follow the rollout:
kubectl apply -f demo.yaml
kubectl -n demo rollout status deployment/web
kubectl -n demo get pods,svc,ingressTest the application from your own computer, even if DNS is not configured yet:
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:
kubectl delete namespace demoAdd an agent node
In this section, AGENT_IP is the IP address of the new node.
Open the traffic between nodes
On the server:
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 udpOn the agent:
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 enablePorts 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:
sudo cat /var/lib/rancher/k3s/server/node-tokenOn 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:
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-pagerOn the server, the new node must appear in the Ready state:
kubectl get nodes -o wideUpdate 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:
curl -sfL https://get.k3s.io | sh -On each agent, pass the same variables again:
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://YOUR_SERVER_IP:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKENIf your cluster is several minor versions behind, upgrade in steps using the matching channel, for example:
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.
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.gzVolumes 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:
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 nodesTroubleshooting
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
sudo journalctl -u k3s -n 80 --no-pager
sudo k3s check-configIf 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
sudo journalctl -u k3s-agent -n 80 --no-pager
curl -vk -m 5 https://YOUR_SERVER_IP:6443/pingconnection refusedor timeout: check UFW and theK3S_URLaddress.- Invalid
token: copy the contents ofnode-tokenagain. 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 withkubectl delete node NODE_NAME.
A node stays in the NotReady state
kubectl describe node NODE_NAME
ip link show flannel-wgCheck ports 10250/TCP and 51820/UDP between the nodes, as well as the node-external-ip values.
A pod stays in Pending or ImagePullBackOff
kubectl -n demo describe pod POD_NAME
kubectl -n demo logs POD_NAMEPending 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
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
/usr/local/bin/k3s-uninstall.shOn an agent:
/usr/local/bin/k3s-agent-uninstall.shGoing further
To store your container images, see the Install Harbor guide. To automate the preparation of your nodes, see Automate Your Servers with Ansible.