FAQ

General

What is k8s-provisioner?

k8s-provisioner is a CLI tool written in Go that automates the creation of Kubernetes clusters for lab and learning environments. It uses VirtualBox and Vagrant to create VMs and provisions a complete Kubernetes stack.

What platforms are supported?

• macOS (Intel and Apple Silicon)
• Linux (x64 and ARM64)
• Windows (x64)

How much RAM do I need?

Default VM allocation:

• Storage: 1 GB
• ControlPlane: 6 GB
• Node01: 8 GB (AI workloads)
• Node02: 4 GB

Kubernetes

What Kubernetes version is used?

Kubernetes 1.32 with CRI-O as the container runtime.

Can I change the number of nodes?

Yes, edit vagrant/settings.yaml to add or remove nodes.

How do I access the cluster from my host?

# Copy kubeconfig
vagrant ssh controlplane -c 'sudo cat /etc/kubernetes/admin.conf' > ~/.kube/config-lab

# Fix API server IP
sed -i '' 's/127.0.0.1/192.168.56.10/' ~/.kube/config-lab   # macOS
sed -i 's/127.0.0.1/192.168.56.10/' ~/.kube/config-lab      # Linux

# Use the config
export KUBECONFIG=~/.kube/config-lab
kubectl get nodes

Components

Why Calico instead of Flannel?

Calico provides network policies and better performance for production-like environments.

Why CRI-O instead of containerd?

CRI-O is a lightweight, Kubernetes-native container runtime. Both work well, but CRI-O is more focused on Kubernetes.

Can I disable Istio?

Currently, Istio is installed by default. You can modify the provisioning scripts to skip it.

Can I disable Karpor/AI?

Yes, set in config.yaml:

components:
  karpor: "none"

karpor_ai:
  enabled: false

This reduces RAM requirements by ~5 GB.

Kubectl Aliases

The following aliases are pre-configured in all VMs:

alias k=kubectl
alias kgp='kubectl get pods'
alias kgs='kubectl get svc'
alias kgn='kubectl get nodes'
alias kga='kubectl get all'
alias kgaa='kubectl get all -A'
alias kd='kubectl describe'
alias kl='kubectl logs'
alias kx='kubectl exec -it'
alias ka='kubectl apply -f'
alias kdel='kubectl delete -f'
alias kn='kubectl config set-context --current --namespace'

Dry-run helper

# Pre-configured variable for dry-run
export do='--dry-run=client -o yaml'

# Example: Create a pod YAML without applying
kubectl run nginx --image=nginx $do > nginx.yaml

Troubleshooting

VMs won’t start

Check VirtualBox is installed and working:

VBoxManage --version

Cluster provisioning fails

Check the logs:

vagrant ssh controlplane
sudo journalctl -u kubelet -f

MetalLB IPs not reachable

Enable promiscuous mode:

k8s-provisioner vbox promisc

Why? MetalLB uses Layer 2 mode (ARP) to announce LoadBalancer IPs. VirtualBox by default blocks ARP traffic between VMs and the host. Promiscuous mode allows the host to receive ARP responses from MetalLB.

Pods stuck in Pending (control-plane taint)

Remove the taint:

kubectl taint nodes controlplane node-role.kubernetes.io/control-plane:NoSchedule-

NFS mount issues

# Check NFS server is running
vagrant ssh storage -c 'systemctl status nfs-kernel-server'

# Check exports
vagrant ssh storage -c 'exportfs -v'

# Test mount from node
vagrant ssh node01 -c 'showmount -e 192.168.56.20'

Clean install (reset everything)

cd vagrant
./clean.sh
vagrant up