KubeVirt Technical Guide: Architecture, Components, Storage, Network, SDK, and Platform Integration

KubeVirt is a Kubernetes plugin that extends the cluster to schedule traditional virtual machines (VMs) in addition to containers by leveraging custom resources (CRDs) and other native Kubernetes features, offering a unified API for VM lifecycle management.

In the author's organization, two separate scheduling platforms existed: OpenStack for bare‑metal and VMs, and Kubernetes for containers, leading to duplicated effort and resource waste. As workloads move to the cloud, the goal became to use Kubernetes as a single scheduler for all runtimes (bare‑metal, VM, Kata, containers) to simplify operations.

After evaluating several projects (KubeVirt, Virtlet, Rancher/VM), KubeVirt was selected due to its active community, design, and alignment with Red Hat's virtualization strategy.

KubeVirt Core Concepts

KubeVirt defines several CRDs (e.g., VirtualMachine, VirtualMachineInstance) and consists of key components: virt-api , virt-controller , virt-handler , and virt-launcher . These components delegate scheduling decisions to Kubernetes while handling VM‑specific tasks.

Common Operations (DomainManager Interface)

type DomainManager interface {

// SyncVMI creates a virtual machine

SyncVMI(*v1.VirtualMachineInstance, bool, *cmdv1.VirtualMachineOptions) (*api.DomainSpec, error)

// PauseVMI pauses a VMI

PauseVMI(*v1.VirtualMachineInstance) error

// UnpauseVMI resumes a paused VMI

UnpauseVMI(*v1.VirtualMachineInstance) error

// DeleteVMI deletes a VMI

DeleteVMI(*v1.VirtualMachineInstance) error

// MigrateVMI triggers live migration

MigrateVMI(*v1.VirtualMachineInstance, *cmdclient.MigrationOptions) error

}

Typical kubectl commands to list VMI and KubeVirt pods are also shown:

kubectl get vmi -o wide

kubectl -n kubevirt get pod

Storage Options

KubeVirt supports multiple disk sources, such as cloudInitNoCloud (user‑data via ConfigMap), dataVolume (auto‑imported PVC), plain PersistentVolumeClaim , and ephemeral containerDisk . Example YAML snippets:

devices:
disks:
- disk:
bus: virtio
name: cloudinit
cloudInitNoCloud:
userData: |
#cloud-config
password: kubevirt

spec:
pvc:
accessModes:
- ReadWriteMany
volumeMode: Block
resources:
requests:
storage: 55G
storageClassName: csi-rbd-sc
source:
http:
url: http://127.0.0.1:8081/CentOS7.4_AMD64_2.1

Networking

KubeVirt relies on the underlying Kubernetes network. The author chose Kube‑OVN (an OVN‑based CNI) to provide L2 VLAN underlay, fixed IP for VMs, and advanced features such as distributed gateways. VMI traffic is carried through a dedicated POD (virt‑launcher) that presents a virtual NIC to the external network.

spec:
cidrBlock: 192.168.10.0/23
gateway: 192.168.10.1
underlayGateway: true
vlan: ovn-vlan

KubeVirt SDK

Both Python and Go SDKs are available. The Python example shows how to create an API client and call the DefaultApi:

import kubevirt
def get_api_client(host):
api_client = kubevirt.ApiClient(host=host, header_name="Content-Type", header_value="application/json")
return api_client
api_client = get_api_client(host="http://127.0.0.1:8001")
api_instance = kubevirt.DefaultApi(api_client)

Because the upstream SDK omitted the newName parameter for VM rename, the author added a custom method:

def v1alpha3_rename_with_http_info(self, name, newName, namespace, **kwargs):
body_params = {"newName": params["newName"]}
api_route = "/apis/subresources.kubevirt.io/v1alpha3/namespaces/{namespace}/virtualmachines/{name}/rename".format(namespace=params["namespace"], name=params["name"])
return self.api_client.call_api(api_route, 'PUT', ...)

Ultron Platform Integration

The internal "Ultron" private‑cloud platform was extended to manage KubeVirt VMs in the same way it manages OpenStack VMs, providing a unified user experience.

Conclusion

KubeVirt offers a practical cloud‑native solution for running VMs alongside containers in private‑cloud environments, addressing many operational pain points of legacy OpenStack deployments, though it may still be less suited for public‑cloud IaaS scenarios.