k3s-vagrant-libvirt

Spin up a local k3s Kubernetes cluster using Vagrant with the libvirt provider. Ideal for local development, testing, and learning Kubernetes without cloud costs.

---

Overview

This project automates the provisioning of a multi-node k3s cluster on KVM/QEMU virtual machines managed by Vagrant. Configuration is kept separate from the Vagrantfile so you can tune the cluster to your needs without editing the core logic.

Prerequisites

Make sure the following are installed on your Linux host:

• Vagrant ≥ 2.3
• vagrant-libvirt plugin
• libvirt / KVM / QEMU
• virt-manager or virsh (optional, for inspection)
• kubectl (to interact with the cluster after provisioning)

Install the vagrant-libvirt plugin:

vagrant plugin install vagrant-libvirt

Ensure your user is in the libvirt group:

sudo usermod -aG libvirt $(whoami)
# Log out and back in for the change to take effect

Getting Started

# Clone the repository
git clone https://github.com/t3rtz4/k3s-vagrant-libvirt.git
cd k3s-vagrant-libvirt

# (Optional) Edit config/ to adjust node count, resources, etc.

# Bring up the cluster
vagrant up

# Check cluster status
vagrant status

Once the cluster is running, retrieve the kubeconfig:

# SSH into the control-plane node
vagrant ssh master

# On the node
cat /etc/rancher/k3s/k3s.yaml

Or copy it to your local machine:

vagrant ssh master -- sudo cat /etc/rancher/k3s/k3s.yaml > ~/.kube/k3s-config
export KUBECONFIG=~/.kube/k3s-config
kubectl get nodes

Configuration

Cluster settings live in the config/ directory. Adjust them before running vagrant up:

Setting	Description
Number of nodes	Control-plane and worker node count
CPUs / Memory	Resources allocated per VM
Box image	Base OS image (e.g. generic/ubuntu2204)
k3s version	Specific k3s release to install
Network	Private network IP range

Repository Structure

k3s-vagrant-libvirt/
├── Vagrantfile        # Main Vagrant configuration
├── config/            # Cluster configuration variables
└── .gitignore

Common Commands

# Start the cluster
vagrant up

# Stop all VMs
vagrant halt

# Destroy the cluster
vagrant destroy -f

# SSH into the control-plane
vagrant ssh master

# SSH into a worker node
vagrant ssh worker1

# Re-run provisioning
vagrant provision

Troubleshooting

Permission denied on libvirt socket Ensure your user is in the libvirt group and re-login.

vagrant up fails with network errors Verify that the default libvirt network is active:

virsh net-list --all
virsh net-start default

kubectl can't connect Make sure KUBECONFIG points to the correct file, or merge the k3s config into your existing ~/.kube/config.

License

This project is open source. See LICENSE for details.