Install K3s (lightweight Kubernetes)

K3s is a lightweight Kubernetes distribution (CNCF), ideal on a HolyCloud Linux VPS with 2 to 4 GB RAM. It bundles containerd, optional Traefik ingress, and a single binary—without the overhead of a full kubeadm cluster.

Prerequisites

• HolyCloud VPS Ubuntu 22.04/24.04 or Debian 12, minimum 2 GB RAM (4 GB recommended in production)
• root or sudo access
• Ports 6443 (API), 10250 (kubelet), and range 30000-32767 (NodePort) open if you expose services
• Resolvable hostname (hostname -f must not return localhost alone)

Tip: create a HolyCloud snapshot before installing an orchestrator. K3s changes iptables/nftables and installs systemd services.

Step 1: system preparation

Update the system and disable swap (required by Kubernetes):

sudo apt update && sudo apt upgrade -y
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

Check kernel modules:

sudo modprobe overlay
sudo modprobe br_netfilter
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

Network parameters:

cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
sudo sysctl --system

Step 2: install K3s (server)

On the primary node of your HolyCloud VPS:

curl -sfL https://get.k3s.io | sudo sh -s - server \
  --write-kubeconfig-mode 644 \
  --tls-san $(curl -s ifconfig.me) \
  --tls-san $(hostname -f)

Wait for startup:

sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes

Kubeconfig for a non-root user:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
export KUBECONFIG=~/.kube/config
kubectl get pods -A

Step 3: join an agent node (optional)

On a second HolyCloud VPS, get the token on the server:

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

On the agent (replace IP_SERVEUR and TOKEN):

curl -sfL https://get.k3s.io | sudo K3S_URL=https://IP_SERVEUR:6443 \
  K3S_TOKEN=TOKEN sh -s - agent

Verify from the server:

kubectl get nodes -o wide

Step 4: deploy a test application

kubectl create deployment nginx-demo --image=nginx:alpine --replicas=2
kubectl expose deployment nginx-demo --port=80 --type=NodePort
kubectl get svc nginx-demo

Note the NodePort (e.g. 31234) and test from your machine:

curl -I http://IP_PUBLIQUE_VPS_HOLYCLOUD:31234

Open that port in UFW and the HolyCloud customer-area firewall if needed.

Step 5: HTTPS ingress (Traefik included)

K3s installs Traefik by default. Example Ingress for a domain pointing to the VPS:

cat <<'EOF' | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts: [www.example.com]
    secretName: demo-tls
  rules:
  - host: www.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-demo
            port:
              number: 80
EOF

For production, install cert-manager or terminate TLS in front of the cluster with Nginx on the same VPS.

Maintenance and uninstall

Update K3s:

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

Full uninstall:

sudo /usr/local/bin/k3s-uninstall.sh
# On an agent:
# sudo /usr/local/bin/k3s-agent-uninstall.sh

Verification

kubectl cluster-info
kubectl get nodes
kubectl get pods -A
sudo journalctl -u k3s -n 50 --no-pager

Need help?

• Pod Pending: insufficient RAM — upgrade the VPS plan or reduce replicas
• API unreachable: port 6443, --tls-san with the VPS public IP
• Conflict with Docker: K3s uses containerd; avoid two runtimes on the same node without advanced config
• HolyCloud support: kubectl get nodes, free -h, sudo systemctl status k3s