Back to Kubernetes

Kubernetes

Install K3s Cluster on Proxmox

A minimal K3s installation guide for lab environments.

kubernetesk3sproxmoxlinux

Overview

This guide demonstrates how to deploy a lightweight K3s Kubernetes cluster on Proxmox VE using Ubuntu virtual machines.

The setup is designed for:

  • homelab environments
  • testing and development
  • lightweight Kubernetes workloads
  • CI/CD experimentation

Architecture

RoleHostnameIP AddressSpecs
Control Planek3s-master-01192.168.1.102 vCPU / 4GB RAM
Worker Nodek3s-worker-01192.168.1.112 vCPU / 4GB RAM
Worker Nodek3s-worker-02192.168.1.122 vCPU / 4GB RAM

Requirements

  • Proxmox VE installed
  • Ubuntu 24.04 LTS VM template
  • Static IP addresses
  • Internet connectivity
  • SSH access

Create Virtual Machines

Recommended VM settings:

SettingValue
OSUbuntu Server 24.04
CPU2 vCPU
Memory4096 MB
Disk32 GB
NetworkVirtIO

Clone the template for:

  • master node
  • worker nodes

Configure Hosts File

Update /etc/hosts on all nodes:

192.168.1.10 k3s-master-01
192.168.1.11 k3s-worker-01
192.168.1.12 k3s-worker-02

Install K3s Server

Run on the master node:

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

Verify installation:

sudo kubectl get nodes

Expected output:

NAME             STATUS   ROLES                  AGE   VERSION
k3s-master-01    Ready    control-plane,master   1m    v1.31.x

Retrieve Node Token

Get the cluster join token:

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

Copy the token.

Join Worker Nodes

Run on each worker node:

curl -sfL https://get.k3s.io | K3S_URL=https://192.168.1.10:6443 K3S_TOKEN=YOUR_TOKEN sh -

Verify Cluster

Run on the master node:

sudo kubectl get nodes

Expected result:

NAME               STATUS   ROLES                  AGE
k3s-master-01      Ready    control-plane,master   5m
k3s-worker-01      Ready    <none>                 2m
k3s-worker-02      Ready    <none>                 2m

Configure kubectl Access

Copy kubeconfig locally:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config

Deploy Test Workload

kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --port=80 --type=LoadBalancer

Verify:

kubectl get pods
kubectl get svc

Troubleshooting

Node Not Joining

Check:

  • firewall rules
  • connectivity to port 6443
  • token correctness

Service Pending External IP

K3s does not include a cloud load balancer by default.

Recommended solutions:

  • MetalLB
  • Traefik ingress
  • NodePort services

Next Steps

Recommended additions:

  • Longhorn storage
  • MetalLB
  • ArgoCD
  • Prometheus + Grafana
  • cert-manager
  • Traefik ingress

References