VirtualMachine Resource Kind

Kind: VirtualMachineapiVersion: pivirt.hu/v1Aliases: vm, vms

The VirtualMachine resource defines the complete specification of a KVM/QEMU virtual guest instance. It declares virtual CPU topologies, guest RAM, virtual disk attachments, network interfaces, firmware attributes (UEFI, Secure Boot, TPM 2.0), and cloud-init bootstrapping.

---

Accepted Kind Aliases

In pivirtctl commands, any of the following aliases are recognized: VirtualMachine, virtualmachine, virtualmachines, virtual-machine, virtual-machines, vm, vms.

---

Example Manifests

Standard Production VM

apiVersion: pivirt.hu/v1
kind: VirtualMachine
metadata:
  name: web-server-01
  labels:
    environment: production
    tier: frontend
    role: web
  annotations:
    description: "Primary NGINX web server"
spec:
  cpu:
    cores: 4
    sockets: 1
    threads: 1
    model: host-passthrough
  memory:
    sizeBytes: 8589934592 # 8 GiB
  disks:
    - name: root-disk
      sizeBytes: 42949672960 # 40 GiB
      format: qcow2
      bus: virtio
      pool: default
      bootIndex: 1
  interfaces:
    - name: eth0
      network: virbr0
      model: virtio
      macAddress: "52:54:00:12:34:56"
  firmware:
    uefi: true
    secureBoot: false
  tpm:
    enabled: true
    version: "2.0"
  cloudInit:
    userData: |
      #cloud-config
      users:
        - name: operator
          sudo: ALL=(ALL) NOPASSWD:ALL
          ssh_authorized_keys:
            - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... admin@pilab
      packages:
        - nginx
        - curl

Minimal Development VM

apiVersion: pivirt.hu/v1
kind: VirtualMachine
metadata:
  name: dev-box
  labels:
    environment: development
spec:
  cpu:
    cores: 2
  memory:
    sizeBytes: 2147483648 # 2 GiB
  disks:
    - name: root
      sizeBytes: 10737418240 # 10 GiB
  interfaces:
    - name: eth0
      network: virbr0

Multi-Disk Database VM

apiVersion: pivirt.hu/v1
kind: VirtualMachine
metadata:
  name: postgres-primary
  labels:
    tier: database
spec:
  cpu:
    cores: 8
  memory:
    sizeBytes: 17179869184 # 16 GiB
  disks:
    - name: os-disk
      sizeBytes: 32212254720 # 30 GiB
      format: qcow2
      bus: virtio
      bootIndex: 1
    - name: pgdata-disk
      sizeBytes: 214748364800 # 200 GiB
      format: raw
      bus: virtio
      pool: fast-nvme
  interfaces:
    - name: eth0
      network: virbr0

---

Specification Reference (spec)

CPU Configuration (spec.cpu)

Field	Type	Required	Default	Description
cores	int	No	2	Number of virtual CPU cores
sockets	int	No	1	Number of CPU sockets
threads	int	No	1	Hyperthreads per core
model	string	No	host-passthrough	QEMU CPU model

Memory Configuration (spec.memory)

Field	Type	Required	Default	Description
sizeBytes	int64	No	2147483648 (2 GiB)	Total guest RAM in bytes

Disks Configuration (spec.disks[])

Field	Type	Required	Default	Description
name	string	Yes		Disk volume identifier
sizeBytes	int64	Yes		Capacity in bytes
format	string	No	qcow2	Image format: qcow2 or raw
bus	string	No	virtio	Bus driver: virtio, scsi, sata, ide
pool	string	No	default	Name of the StoragePool holding this disk
bootIndex	int	No		Firmware boot order priority (1 for primary boot disk)
readonly	bool	No	false	Mount disk as read-only

Network Interfaces (spec.interfaces[])

Field	Type	Required	Default	Description
name	string	Yes		Interface name inside manifest (e.g. eth0)
network	string	Yes		Name of target Network or host bridge (e.g. virbr0, br0)
model	string	No	virtio	Virtual NIC model: virtio, e1000, rtl8139
macAddress	string	No	Auto-generated	Hardware MAC address

Firmware & Security (spec.firmware & spec.tpm)

Field	Type	Required	Default	Description
firmware.uefi	bool	No	true	Boot using OVMF UEFI firmware
firmware.secureBoot	bool	No	false	Enable Secure Boot support
tpm.enabled	bool	No	false	Attach software TPM 2.0 emulator (swtpm)
tpm.version	string	No	"2.0"	TPM specification version

Cloud-Init (spec.cloudInit)

Field	Type	Required	Default	Description
userData	string	No		Complete #cloud-config user-data payload

---

Runtime Status (status)

When queried with pivirtctl get vm <name> -o yaml, pivirtd returns observed runtime telemetry:

status:
  phase: Running                      # Running, Stopped, Paused, Crashed
  observedGeneration: 2
  pid: 41209
  qmpSocket: /var/lib/pivirt/vms/web-server-01/run/qmp.sock
  conditions:
    - type: Ready
      status: "True"
      lastTransitionTime: "2026-09-07T00:15:00Z"

---

CLI Management Examples

# Apply manifest
pivirtctl apply -f web-server-01.yaml

# List all VMs
pivirtctl get vms

# Filter VMs by label
pivirtctl get vms -l "environment=production"

# Inspect VM details
pivirtctl describe vm web-server-01

# Start or stop the VM
pivirtctl vm start web-server-01
pivirtctl vm stop web-server-01

# Delete VM with cascading disk teardown
pivirtctl delete vm web-server-01