SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

K3s for One VPS: E Get Sense Pass Docker Compose?

K3s gives you the real Kubernetes API on one VPS, but e dey use RAM and port 80 fit collide during install. See when Docker Compose still better.

Wetin k3s be, and wetin one node of am give you

k3s na complete Kubernetes distribution wey dem package as one binary. If you run am for one VPS, you get the real Kubernetes API without three-machine control plane. Na certified Kubernetes distribution, so any manifest wey apply here go still apply for managed cluster later. Installation na one command and e dey take about one minute. Wetin you pay na memory wey your applications no fit use again, plus some failure modes wey no dey happen with Docker Compose.

SUSE build k3s for edge sites and small installations. The differences between k3s and upstream Kubernetes dey make am smaller and easier to run. The default datastore na sqlite behind shim wey dem call kine, no be etcd, so you no need maintain etcd quorum. containerd dey embedded inside the binary instead of installing am separately. The same binary also ship CoreDNS for cluster DNS, Traefik as ingress controller, ServiceLB (wey dem also call klipper-lb) so LoadBalancer services fit work without cloud provider, local-path provisioner for persistent volumes, metrics-server, and flannel for pod networking. All of dem start by default. These defaults put Traefik for ports 80 and 443, so decide who go use those ports before you install am for VPS wey already dey serve something.

When one k3s node dey make sense

Use this rule. Run k3s when na Kubernetes API you want: you dey learn Kubernetes for machine wey you control, or the software wey you want only publish Helm chart. Manifest portability dey count too, because Deployment wey you write here fit move go managed cluster unchanged. Run Docker Compose when na the applications you want. Compose start the same containers with far fewer moving parts, and Compose file for VPS easier to read one year later than directory of manifests.

Make you understand wetin one node no fit give you.

  • No high availability. When VPS reboot, every workload stop. Kubernetes fit reschedule pod go another node, but no other node dey.
  • No rolling update wey keep service running, unless application fit handle two replicas for one machine and the node get enough space for both.
  • Storage wey dey tied to the machine, for the reason wey the local-path section below explain.
  • Control plane wey dey use around one gigabyte of RAM whether you deploy anything or not.

None of this mean say k3s na bad choice. E mean say e na bad choice for the reason people usually give, wey be reliability. If wetin you really want na several machines so you fit build real multi-node cluster, make that decision first: Proxmox for your own hardware against rented VPS go settle where the nodes go come from before k3s settle wetin go run on dem.

Wetín k3s dey cost for RAM and CPU before you deploy anything

The k3s project dey publish measured figures, no be estimates. Read dem carefully, because the number wey people dey quote no be idle k3s.

ChartPublished k3s resource use, 95th percentile, Intel 8375C, k3s v1.26.5
Di data wey dey behind dis chart
[
  {
    "label": "Server, sqlite datastore",
    "ram_mb": "1,596",
    "cpu_percent_of_one_core": 6
  },
  {
    "label": "Server, embedded etcd",
    "ram_mb": "1,606",
    "cpu_percent_of_one_core": 6
  },
  {
    "label": "Agent node only",
    "ram_mb": "275",
    "cpu_percent_of_one_core": 3
  }
]

A server node for that test use 1,596 MB of RAM for the 95th percentile and about 6 percent of one core. Those figures na published figures, no be measurements from this guide. The test run k3s v1.26.5 with all packaged components enabled, plus Prometheus and Grafana monitoring stack. So the cluster dey busy, no be empty. But the project talk say the figures cover only the Kubernetes datastore and control plane, and dem exclude requirements wey depend on workloads. Your own containers go add on top. When sqlite change to embedded etcd, RAM move to 1,606 MB. An agent node, wey dey run kubelet and containerd without control plane, use 275 MB. The documented minimum for one server na 2 cores and 2 GB of RAM. That minimum cover k3s and its packaged components before your workloads.

The practical meaning be say: for a 2 GB VPS, the control plane and bundled add-ons go leave you with very little memory. When memory pressure happen, kubelet fit evict pods. But if memory usage rise quickly, the kernel's OOM killer fit act before kubelet detect the pressure. 4 GB na comfortable minimum for one node with a few small services. Measure your own box instead of trusting any published figure, including this one.

free -h
sudo k3s kubectl top node
sudo k3s kubectl get pods -A

Run free -h before you install, and run am again after every pod for kube-system don read Running. The difference na wetin the control plane dey cost for your hardware. k3s kubectl top node go return error: Metrics API not available for the first minute or two after installation, because metrics-server never scrape anything yet. That one no be fault. If you dey size one box for this work and other work at the same time, the arithmetic for sizing RAM and CPU for a VPS still apply here without change.

Install k3s wey pin to one release, no be latest

The quick start line wey everybody dey copy go use whichever release stable channel point to on the day wey you run am. For machine wey you plan to keep, pin am. k3s dey publish one channel for each Kubernetes minor version, so INSTALL_K3S_CHANNEL=v1.36 dey follow patch releases inside v1.36 and e no go jump to another minor version by itself. As of October 2026, stable channel dey point to v1.36.5+k3s1.

Write the config file first, then install. k3s dey read /etc/rancher/k3s/config.yaml when e start, so anything wey dey inside am go apply for the first boot and every boot after that.

sudo mkdir -p /etc/rancher/k3s
sudo tee /etc/rancher/k3s/config.yaml >/dev/null <<'EOF'
tls-san:
  - k3s.example.com
EOF
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=v1.36 sh -

To pin one exact release instead of a channel, use INSTALL_K3S_VERSION=v1.36.5+k3s1. The plus sign na part of the tag. Then check say e don come up.

k3s --version
sudo systemctl status k3s
sudo k3s kubectl get node
sudo k3s kubectl get pods -A

kubectl get node suppose list one node with STATUS Ready within about thirty seconds, and every pod for kube-system suppose reach Running or Completed. If node remain for NotReady, e usually mean say container runtime never start, so read sudo journalctl -u k3s -n 100 --no-pager. For unusual VPS image, run sudo k3s check-config before you debug anything else: e go report kernel features wey dey missing, and this answer dey much faster than reading logs.

Port 80 dey already use: wetin you fit give up to fix am

Na this failure dey catch people for VPS wey don already dey serve something. The install dey succeed, but Traefik no go get address if another Kubernetes pod don already reserve the same hostPort for the only node.

The mechanism be say: the bundled Traefik chart dey create Service of type LoadBalancer for ports 80 and 443. ServiceLB dey answer that request by creating DaemonSet of small pods, wey dem name with svclb- prefix, and dem claim those port numbers as hostPort for each node. hostPort dey forward traffic from node port go the pod through network rules. The scheduler dey check host ports wey Kubernetes pods declare, not sockets wey host services or standalone Docker containers hold. If another pod reserve the same hostPort, e go block scheduling; nginx, Caddy, Apache or standalone Docker container wey dey listen on port 80 no cause that scheduling rejection by itself.

sudo k3s kubectl -n kube-system get pods
sudo k3s kubectl -n kube-system get svc traefik
sudo ss -lntp '( sport = :80 or sport = :443 )'

If another Kubernetes pod reserve the hostPort and conflict dey, you go see the svclb pod as Pending and the service without external address:

svclb-traefik-8f2c1a-r6k9x   0/2   Pending   0   3m
traefik   LoadBalancer   10.43.62.11   <pending>   80:31480/TCP,443:30219/TCP

If you run kubectl -n kube-system describe pod svclb-traefik-..., e go show the cause directly:

0/1 nodes are available: 1 node(s) didn't have free ports for the requested pod ports.

ss -lntp go tell you which process dey listen on the port; e no show the hostPort reservations wey scheduler dey check. More than one solution dey, and each one get wetin you go give up.

Give the ports to k3s. Remove any conflicting hostPort reservation from another Kubernetes pod, then stop and disable the existing host web server so Traefik fit handle incoming traffic for 80 and 443. Na the correct choice if the VPS go become k3s box and nothing else, and everything wey you dey serve go move behind an Ingress.

Disable ServiceLB and keep your existing proxy. Install am with --disable=servicelb. Service of type LoadBalancer still dey allocate NodePort, so Traefik remain reachable for high port like 31480, and your nginx or Caddy go proxy to 127.0.0.1:31480. The thing wey you give up na the external address: the service go report <pending> forever. E fit look like fault, but na choice you make.

Disable Traefik and route with your own proxy. Install am with --disable=traefik. You no go get ingress controller again, so Ingress objects no go do anything: dem go sit for the API without controller wey dey watch dem. This one dey okay if you dey route from host proxy to NodePorts, and na the honest choice if you already know how you want HTTP handling to work. If you never decide wetin go dey in front, settle the choice between nginx, Caddy and Traefik as reverse proxy before you disable anything.

Both flags belong on the installer, or inside the config file:

tls-san:
  - k3s.example.com
disable:
  - traefik
  - servicelb

If you edit that file after installation and run sudo systemctl restart k3s, e go still work because --disable no just skip component during install. E also delete component wey don already deploy, so the change go take effect for cluster wey dey run.

If you want keep Traefik but change how the chart dey configured, no edit /var/lib/rancher/k3s/server/manifests/traefik.yaml. k3s dey rewrite that file with defaults every time e start. Add separate file for the same directory instead, because anything inside /var/lib/rancher/k3s/server/manifests dey apply automatically when startup happen and whenever the file change for disk.

apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    ports:
      web:
        forwardedHeaders:
          trustedIPs:
            - 10.0.0.0/8

That example dey set one Traefik chart value: the trusted proxy addresses. You fit use the same mechanism set any other value wey the chart expose, including its ports.

Persistent storage for one node

k3s dey ship with default StorageClass wey dem call local-path, and Rancher local-path provisioner dey back am. PersistentVolumeClaim wey no get storageClassName go use am. Volumes dey live for /var/lib/rancher/k3s/storage, with one subdirectory for each volume, for the node own disk.

sudo k3s kubectl get storageclass
sudo k3s kubectl get pvc -A
sudo ls -l /var/lib/rancher/k3s/storage

Two things dey follow from “for the node own disk”, and both fit cause problem later, no be today.

The StorageClass dey use volumeBindingMode: WaitForFirstConsumer, so new PVC go remain Pending until pod actually mount am. kubectl describe pvc dey print:

waiting for first consumer to be created before binding

This one normal, so if you create PVC by itself and wait, e no go ever clear.

After volume don bind, e go carry node affinity for the node wey create am. This one pin every pod wey dey use that claim to the same node for the whole life of the volume. For one node, you no go notice am. If you add second node later and pod refuse move, e go look like scheduler bug until you run kubectl get pv -o yaml and discover the hostname inside nodeAffinity.

Na you get responsibility for backups. If you rebuild the VPS, that directory go disappear. The uninstall script below go also delete am. Back up /var/lib/rancher/k3s/storage, the sqlite datastore directory /var/lib/rancher/k3s/server/db/ copied while the service dey stopped because na live database, and the server token file for /var/lib/rancher/k3s/server/token. The token no be optional: k3s documentation talk say you must restore that file, or pass its value to --token, when you restore the datastore from backup. Another option na to treat the cluster as disposable and keep every manifest for git.

Ingress and TLS

If you leave Traefik enabled, standard Ingress object na all you need.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hello
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
spec:
  ingressClassName: traefik
  tls:
    - hosts:
        - hello.example.com
      secretName: hello-tls
  rules:
    - host: hello.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: hello
                port:
                  number: 80

Certificates no dey appear by themselves. The usual solution na cert-manager, installed from the manifest wey dem publish, plus one ClusterIssuer. Version v1.21.3, released on 23 October 2026, na the current version as of October 2026.

sudo k3s kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.21.3/cert-manager.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt
spec:
  acme:
    email: you@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: traefik

The HTTP-01 challenge mean say the ACME (automatic certificate management environment) server go connect to http://hello.example.com/.well-known/acme-challenge/... from public internet. So the hostname DNS record, either an A record or an AAAA record if the VPS dey reachable over IPv6, must already point to the VPS, and port 80 must reach Traefik. Let's Encrypt dey try the IPv6 address first when both addresses dey, but e go fall back to IPv4 if the first IPv6 connection times out. Other errors, including wrong challenge response, no trigger this fallback, and redirected requests no get the retry. Fix or remove stale AAAA record. If you disable ServiceLB and put your own proxy in front, that proxy must forward the challenge path too. Otherwise, cert-manager go stall with this message for the Challenge object:

Waiting for HTTP-01 challenge propagation: wrong status code '404', expected '200'

Monitor issuance with sudo k3s kubectl describe certificate hello-tls and sudo k3s kubectl get order,challenge -A.

kubeconfig, and why API server dey stay private

k3s dey write admin credentials to /etc/rancher/k3s/k3s.yaml. root own the file, and by default e dey write am with mode 600. E hold client certificate wey get cluster-admin rights, so anybody wey fit read am don control the cluster.

sudo k3s kubectl get node
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get node

kubectl wey you install separately no sabi the k3s file. If KUBECONFIG no set, e dey read ~/.kube/config, and if that file no dey, e go fail with The connection to the server localhost:8080 was refused - did you specify the right host or port? because no cluster configure for am. Set KUBECONFIG, copy the file to ~/.kube/config as e show below, or use sudo k3s kubectl, wey dey read the correct file by itself.

You go see say dem recommend --write-kubeconfig-mode 644 so normal user fit run kubectl. Understand wetin that one do: e make cluster-admin credential readable by every local account for the machine. For machine wey one admin dey use, that fit be acceptable trade-off. For shared machine, e no safe. If you copy the file instead, na only one user get access without exposing am:

mkdir -p ~/.kube
sudo install -o $USER -g $USER -m 600 /etc/rancher/k3s/k3s.yaml ~/.kube/config

The server: line for that file dey read https://127.0.0.1:6443. To use kubectl from your laptop, no open 6443 to the internet. Public Kubernetes API dey attract continuous attacks, and exposed API fit make small clusters become cryptocurrency mining machines for another person. Tunnel am through SSH, and leave the address for the file as e dey:

ssh -N -L 6443:127.0.0.1:6443 user@your-vps
KUBECONFIG=./k3s.yaml kubectl get node

If you must reach the API through private network address, install am with tls-san wey list that name or address, then edit the copied file server: line to match. If SAN (subject alternative name) entry no dey, kubectl go reject the connection:

x509: certificate is valid for 127.0.0.1, 10.43.0.1, not 203.0.113.10

The documented inbound ports for cluster na TCP 6443 for API, UDP 8472 for flannel VXLAN between nodes, and TCP 10250 for kubelet metrics. For single-node setup, none of dem need make e open to internet.

containerd no be Docker

k3s dey run im own embedded containerd, and e no share image store with Docker. Image wey you just build with docker build no dey visible to k3s, so the pod fails with ErrImagePull even though docker images list am. Import am explicitly:

docker save myapp:0.1 | sudo k3s ctr images import -
sudo k3s crictl images

Then avoid :latest tag for that container, because :latest default to imagePullPolicy of Always and kubelet go registry anyway. Any other tag default to IfNotPresent, wey dey use the image wey you import. Running both for one VPS dey work, and e good make you know say normal Docker installation for VPS and k3s each keep their own image store and their own iptables rules for the same machine.

How to remove k3s

Installer dey write uninstall script. Partial removal no dey, and you no fit undo am.

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

E go stop and remove the service, delete the datastore, delete persistent volume data, remove the node configuration, and remove the tools wey installer add. For agent node, the script na k3s-agent-uninstall.sh instead. First copy anything wey dey under /var/lib/rancher/k3s/storage comot from the machine, because that directory go delete too. Afterward, use ip link show and sudo ss -lntp check say nothing still dey hold ports or interfaces. Any leftover cni0 or flannel.1 interface go clear for the next reboot.

To decide say one Kubernetes node na more machinery than the job need na normal outcome; e no mean say you fail. Moving those workloads back to Compose usually fit happen within one afternoon.

Failure modes and the strings wey you go see

Node NotReady, or k3s dey restart for loop. Read sudo journalctl -u k3s -n 200 --no-pager first. For small VPS, common cause na kernel out-of-memory killer wey dey stop the process. You go see am for dmesg as line wey name k3s-server. The documented 2 GB minimum na real minimum.

Pod dey stuck for Pending. kubectl describe pod go name the reason every time. Insufficient memory or Insufficient cpu mean say node no get space again. didn't have free ports mean say another Kubernetes pod don reserve conflicting hostPort. waiting for first consumer for PVC mean say WaitForFirstConsumer dey work as e suppose.

ImagePullBackOff. Node no fit pull the image. Check image name and tag, registry access and credentials, or whether you build the image with Docker but never import am into containerd.

Traefik dey answer, but app no dey. Response body of 404 page not found come from Traefik itself. E mean say request reach there, but no router match am. Check say Ingress host match the name wey you type, and say ingressClassName na traefik.

Cluster DNS dey fail while host dey resolve well. Check CoreDNS with sudo k3s kubectl -n kube-system logs -l k8s-app=kube-dns. Message like plugin/loop: Loop ... detected for zone "." go stop CoreDNS from starting. E dey happen because CoreDNS dey forward to resolver wey dey forward back to am. Na wetin loopback address for /etc/resolv.conf dey cause. Point k3s to the real upstream file with --resolv-conf /run/systemd/resolve/resolv.conf.

FAQ

k3s worth running for one VPS?

E worth am when na Kubernetes API be wetin you want: to learn am for machine wey you control, keep deployments portable as manifests, run software wey only publish Helm chart, or build something wey you go later move go managed cluster. E no worth am when na only containers you want make dey run, because Docker Compose fit do am with much less thing to maintain and roughly one gigabyte more free RAM. One node no give you high availability, so reliability no be reason to choose am.

Why my k3s LoadBalancer service dey stay Pending?

ServiceLB dey create svclb- pods wey claim the service ports as hostPort for the node, so dem fit only schedule where those ports dey free. If another Kubernetes pod don already reserve the same hostPort, the pod go remain Pending and the service no go ever receive external address. Host proxy or standalone Docker container wey dey listen on port 80 no cause this scheduling rejection by itself. kubectl -n kube-system describe pod svclb-... dey report 0/1 nodes are available: 1 node(s) didn't have free ports for the requested pod ports. Remove the conflicting pod hostPort reservation, or disable ServiceLB with --disable=servicelb and proxy to the NodePort wey the service still allocates.

How much RAM k3s need for VPS?

The documented minimum for server node na 2 cores and 2 GB, and this cover k3s plus the components wey e package before your workloads. The project own profiling measure the control plane and datastore of server node at 1,596 MB while monitoring stack dey run on top, and that figure no include the workload own memory. So treat 2 GB as the floor and 4 GB as the first size where one node go comfortable. Measure your own box with free -h before the install, then measure am again after every pod inside kube-system read Running.

I fit run Docker and k3s for the same VPS?

Yes, and dem remain separate. k3s dey use im own embedded containerd, so image wey you build with docker build no dey visible to am until you run docker save myapp:0.1 | sudo k3s ctr images import -. Each one also dey write im own iptables rules and im own bridge networks. Monitor the total memory, because Docker, k3s and your containers all dey share the box RAM.

How I fit remove k3s completely?

Run sudo /usr/local/bin/k3s-uninstall.sh for server node, or sudo /usr/local/bin/k3s-agent-uninstall.sh for agent. E go stop the service, delete the datastore, delete persistent volume data under /var/lib/rancher/k3s/storage, and remove the bundled tools. Copy any data wey you want keep off the box first, because no undo dey. Any leftover cni0 or flannel.1 network interface go disappear for the next reboot.

Dis article help you?

#kubernetes#k3s#docker-compose#ingress#sizing