Introduction

Running Kubernetes on Proxmox LXC containers is possible, but it requires careful container privilege and kernel feature settings. Unlike full virtual machines, LXC shares the host kernel, so missing cgroup or namespace capabilities can break kubelet startup. A stable setup starts with correctly configured privileged containers, networking, and runtime prerequisites before cluster bootstrap.

Plan Topology and Proxmox Container Settings

Define at least one control-plane node and one worker node. For learning clusters, three containers are common:

• k8s-cp-1
• k8s-worker-1
• k8s-worker-2

In Proxmox, create containers with enough memory and CPU. Kubernetes control plane in LXC is sensitive to low memory pressure.

Important container options:

• nested containers enabled
• keyctl enabled
• cgroup access enabled
• privileged mode preferred for simpler setup

After creating containers, verify network reachability between nodes with static IP assignments.

Prepare Each LXC Node for Kubernetes

Install base packages and disable swap.

1sudo apt-get update
2sudo apt-get install -y curl ca-certificates gnupg lsb-release
3sudo swapoff -a
4sudo sed -i '/ swap / s/^/#/' /etc/fstab

Load required kernel modules and sysctl settings:

1cat <<'EOF_SYSCTL' | sudo tee /etc/modules-load.d/k8s.conf
2overlay
3br_netfilter
4EOF_SYSCTL
5
6sudo modprobe overlay
7sudo modprobe br_netfilter
8
9cat <<'EOF_SYS' | sudo tee /etc/sysctl.d/k8s.conf
10net.bridge.bridge-nf-call-iptables = 1
11net.bridge.bridge-nf-call-ip6tables = 1
12net.ipv4.ip_forward = 1
13EOF_SYS
14
15sudo sysctl --system

These settings are mandatory for pod networking and service routing.

Install Container Runtime and Kubernetes Components

Install containerd and Kubernetes binaries on all nodes.

1sudo apt-get install -y containerd
2sudo mkdir -p /etc/containerd
3containerd config default | sudo tee /etc/containerd/config.toml >/dev/null
4sudo systemctl restart containerd
5sudo systemctl enable containerd

Install kubeadm stack:

1sudo apt-get update
2sudo apt-get install -y apt-transport-https
3curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
4echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
5sudo apt-get update
6sudo apt-get install -y kubelet kubeadm kubectl
7sudo apt-mark hold kubelet kubeadm kubectl

Adjust version stream to your desired Kubernetes minor release.

Initialize Control Plane and Join Workers

On control-plane container:

sudo kubeadm init --pod-network-cidr=10.244.0.0/16

Configure kubectl for your user:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown "$(id -u):$(id -g)" $HOME/.kube/config

Install CNI plugin. Flannel example:

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

Then run the kubeadm join command shown by init on each worker node.

Proxmox and LXC-Specific Troubleshooting

Common errors on LXC clusters include kubelet crash loops tied to missing cgroup features or permission limits.

Diagnostic commands:

1sudo systemctl status kubelet --no-pager
2sudo journalctl -u kubelet -n 200 --no-pager
3kubectl get nodes -o wide
4kubectl get pods -A

If kubelet reports cgroup driver mismatch, align containerd and kubelet drivers. Also ensure Proxmox host kernel supports required cgroup versions consistently.

Networking errors often come from bridge settings on Proxmox host. Confirm containers can ping each other by IP before blaming CNI.

Production Notes and Safer Alternatives

LXC-based Kubernetes is excellent for labs and constrained homelabs, but production clusters usually run on VMs or bare metal for stronger isolation and fewer kernel coupling issues. If you need high reliability, consider Proxmox VMs with cloud-init automation.

Still, for development clusters, LXC can be fast and resource-efficient when configuration is documented and reproducible.

Common Pitfalls

• Creating unprivileged LXC containers without required kernel capabilities.
• Forgetting to disable swap before kubeadm initialization.
• Skipping cgroup and sysctl preparation steps.
• Expecting CNI to work when node-to-node container networking is already broken.
• Treating LXC lab setup as production-ready without isolation analysis.

Summary

• Kubernetes on Proxmox LXC works when container capabilities are configured correctly.
• Prepare kernel modules, sysctl, runtime, and kubeadm dependencies on every node.
• Initialize control plane first, then install CNI and join workers.
• Use kubelet logs and node-level networking checks for troubleshooting.
• Prefer VMs for production and LXC for efficient lab environments.