A minimal web app to manage KubeVirt VirtualMachines in a single namespace or across multiple namespaces.
- Frontend: Static HTML/CSS/JS in
app/static/ - Backend: FastAPI serving REST and WebSocket proxy
- Target namespace: from
POD_NAMESPACEenv
This repository is provided for hobby and educational purposes only. If you plan to use it in a production environment, it will most likely require significant customization, testing, and security audits. Please fork and build your own application.
- Bearer token auth (simple): supply a token in the login modal. Backend validates against
API_TOKEN. - List VMs in namespace (or across all namespaces in Admin Mode)
- Start/Stop/Restart VMs
- VNC console access
- Serial console access
- Admin Mode for managing VMs across multiple namespaces
- Session timeout for security
- Responsive web interface
Base: /api/v1
GET /namespace→ Get current namespaceGET /vms/{namespace}→ List VMs in specified namespace[ { name, namespace, status } ]POST /vms/{namespace}/{name}/start→ Start VMPOST /vms/{namespace}/{name}/stop→ Stop VMPOST /vms/{namespace}/{name}/restart→ Restart VMPOST /vms/{namespace}/{name}/console-token→ Generate temporary token for console accessWebSocket /vms/{namespace}/{name}/console→ Serial console WebSocketWebSocket /vms/{namespace}/{name}/vnc→ VNC console WebSocketGET /health→ Liveness/readiness
GET /namespace→ Get current namespace and admin mode statusGET /namespaces→ List all namespaces with kubevirt.io/namespace= labelGET /vms/{namespace}→ List VMs in specified namespace[ { name, namespace, status } ]POST /vms/{namespace}/{name}/start→ Start VM in specified namespacePOST /vms/{namespace}/{name}/stop→ Stop VM in specified namespacePOST /vms/{namespace}/{name}/restart→ Restart VM in specified namespacePOST /vms/{namespace}/{name}/console-token→ Generate temporary token for console accessWebSocket /vms/{namespace}/{name}/console→ Serial console WebSocketWebSocket /vms/{namespace}/{name}/vnc→ VNC console WebSocketGET /health→ Liveness/readiness
Static UI available at / and served at /static/*.
Set these environment variables:
ADMIN_MODE— set admin mode to access all VMs across namespaces (defaultfalse)POD_NAMESPACE— target namespace (defaultdefault). Ignored in ADMIN_MODE.API_TOKEN— token accepted by the API (used by UI)LOG_LEVEL— logging level (defaultINFO, options:TRACE,DEBUG,INFO,WARNING,ERROR,CRITICAL)
The included manifests already inject POD_NAMESPACE and API_TOKEN using a ServiceAccount and Secret.
Prereqs: Python 3.11+, access to a cluster (via kubeconfig), and KubeVirt installed.
# from repo root
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
export POD_NAMESPACE=default
export API_TOKEN=devtoken123
# Optional: set logging level (default is INFO)
# export LOG_LEVEL=DEBUG
# use your cluster kubeconfig
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reloadOpen http://localhost:8000, enter your API token, manage VMs.
# optional: set image tag
IMAGE=${IMAGE:-simple-virtmgr:dev}
docker build -t "$IMAGE" .# Create namespace
kubectl create namespace simple-virtmgr
# Create secret with your desired API token
kubectl apply -f manifests/simple-virtmgr-user/secret.yaml
# RBAC, Service, Deployment
kubectl apply -f manifests/simple-virtmgr-user/rbac.yaml
kubectl apply -f manifests/simple-virtmgr-user/service.yaml
kubectl apply -f manifests/simple-virtmgr-user/deployment.yaml# Create namespace
kubectl apply -f manifests/simple-virtmgr-admin/namespace.yaml
# Create secret with your desired API token
kubectl apply -f manifests/simple-virtmgr-admin/secret.yaml
# RBAC, Service, Deployment
kubectl apply -f manifests/simple-virtmgr-admin/rbac.yaml
kubectl apply -f manifests/simple-virtmgr-admin/service.yaml
kubectl apply -f manifests/simple-virtmgr-admin/deployment.yamlUpdate the image: field in the deployment YAML files if you built a custom image.
This project is licensed under the MIT License - see the LICENSE file for details.