Setting Up Kubernetes on Proxmox VE

Why Run Kubernetes on Proxmox?

Proxmox VE is an excellent platform for running Kubernetes clusters. You get full control over the underlying infrastructure, hardware-level isolation between nodes, and the ability to snapshot and back up your entire cluster. Whether you are learning Kubernetes for career development or running production workloads at home, Proxmox provides the foundation you need.

This guide covers two approaches: k3s for a lightweight, quick setup, and kubeadm for a full-featured, production-style cluster.

Preparing VM Templates with Cloud-Init

The first step is creating a reusable VM template with cloud-init so you can rapidly spin up cluster nodes. Download a cloud image and create the template from the Proxmox host shell:

# Download Ubuntu 24.04 cloud image
wget https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

# Create a new VM
qm create 9000 --name ubuntu-cloud --memory 2048 --cores 2 --net0 virtio,bridge=vmbr0

# Import the cloud image as the VM disk
qm importdisk 9000 noble-server-cloudimg-amd64.img local-lvm

# Attach the disk, add cloud-init drive, and configure boot
qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-0
qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot c --bootdisk scsi0
qm set 9000 --serial0 socket --vga serial0
qm set 9000 --agent enabled=1

# Set cloud-init defaults
qm set 9000 --ciuser admin --cipassword yourpassword
qm set 9000 --ipconfig0 ip=dhcp
qm set 9000 --sshkeys ~/.ssh/authorized_keys

# Resize disk to 20GB and convert to template
qm resize 9000 scsi0 20G
qm template 9000

Now clone this template for each Kubernetes node. For a basic cluster, create one control plane node and two worker nodes:

# Clone nodes from template
qm clone 9000 101 --name k8s-master --full
qm clone 9000 102 --name k8s-worker1 --full
qm clone 9000 103 --name k8s-worker2 --full

# Set static IPs for each node
qm set 101 --ipconfig0 ip=10.0.0.101/24,gw=10.0.0.1
qm set 102 --ipconfig0 ip=10.0.0.102/24,gw=10.0.0.1
qm set 103 --ipconfig0 ip=10.0.0.103/24,gw=10.0.0.1

Option 1: Installing k3s (Lightweight)

k3s is a certified Kubernetes distribution that uses fewer resources and installs in seconds. It is ideal for homelabs and edge deployments. SSH into your master node and run:

# Install k3s on the master node
curl -sfL https://get.k3s.io | sh -

# Get the node token (needed for workers)
sudo cat /var/lib/rancher/k3s/server/node-token

# Copy the kubeconfig for kubectl access
sudo cat /etc/rancher/k3s/k3s.yaml

On each worker node, join the cluster using the token:

# Join worker to the k3s cluster
curl -sfL https://get.k3s.io | K3S_URL=https://10.0.0.101:6443 \
  K3S_TOKEN=your-node-token-here sh -

Option 2: Installing with kubeadm (Full Featured)

For a standard Kubernetes cluster, install the required packages on all nodes, then initialize the control plane:

# On all nodes: install containerd, kubelet, kubeadm, kubectl
sudo apt update && sudo apt install -y apt-transport-https curl
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt update && sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

# On the master node: initialize the cluster
sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=10.0.0.101

# Set up kubectl for your user
mkdir -p $HOME/.kube
sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

Networking: Calico vs Flannel

Every Kubernetes cluster needs a CNI (Container Network Interface) plugin. The two most popular choices are:

• Flannel — Simple overlay network, easy to set up, minimal configuration. Best for homelabs and learning.
• Calico — Full-featured with network policies, BGP peering, and better performance. Best for production or when you need fine-grained network control.

# Install Flannel
kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

# OR install Calico
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.0/manifests/tigera-operator.yaml
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.0/manifests/custom-resources.yaml

Persistent Storage with CSI Drivers

Kubernetes pods are ephemeral, so you need a storage solution for stateful workloads. On Proxmox, popular options include:

• democratic-csi with NFS/iSCSI — Connect to a TrueNAS or Proxmox NFS share for dynamic provisioning.
• Longhorn — Distributed block storage built for Kubernetes, easy to install and manage.
• local-path-provisioner — Bundled with k3s, uses local node storage. Simple but not replicated.

# Install Longhorn for distributed storage
kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.7.0/deploy/longhorn.yaml

# Verify Longhorn pods are running
kubectl -n longhorn-system get pods

Managing Your Cluster

With Kubernetes running on Proxmox, you will want to keep an eye on both layers of your infrastructure. Use kubectl get nodes and kubectl top nodes for cluster-level health, and the Proxmox web UI for hypervisor-level metrics. For quick mobile monitoring of the underlying Proxmox nodes — checking if a VM is running, verifying CPU and memory pressure, or restarting a stuck node — ProxmoxR is a convenient way to manage the infrastructure layer from your phone without needing SSH or a browser.

Start with k3s if you are new to Kubernetes, and consider kubeadm when you need more control. Either way, Proxmox gives you a solid, flexible foundation for your cluster.