Workload Config

Workloads in Mesh Hypervisor are KVM virtual machines defined by config files in /var/pxen/monoliths/ on the central orchestration node, uploaded to remote nodes via mesh workload start. This section fully explains the config structure, keys, and validation, based on the QEMU start script. For usage, see Configuring Workloads.

Overview

Each config file is a key-value text file (e.g., qemutest1.conf) specifying a VM’s name, UUID, resources, disks, network, and console. It’s parsed on the remote node to build a qemu-system-x86_64 command. Keys use dot notation (e.g., platform.cpu.threads), and invalid configs halt startup with errors.

Structure and Keys

Required Keys

  • name:
    • Format: String (e.g., qemutest1).
    • Purpose: VM identifier, matches -w in mesh workload commands.
    • Validation: Must be set or startup fails.
  • uuid:
    • Format: Unique string (e.g., qweflmqwe23).
    • Purpose: Internal VM ID, used for monitor files (e.g., /tmp/pxen/<uuid>/).
    • Validation: Must be unique and set, or startup fails.

Platform Settings

  • platform.memory.size:
    • Format: Number + unit (K, M, G, T) (e.g., 4G, 500M).
    • Purpose: Sets VM RAM as QEMU’s -m arg.
    • Validation: Must match ^[0-9]+[KMGT]$, fit node’s available memory (MemAvailable in /proc/meminfo), or fail.
  • platform.cpu.threads:
    • Format: Integer (e.g., 2).
    • Purpose: Sets vCPU threads as QEMU’s -smp arg.
    • Validation: Must be a positive number, ≤ node’s CPU threads (nproc), or fail.
  • platform.cpu.mode:
    • Format: QEMU CPU model (e.g., Penryn-v1) or host.
    • Purpose: Sets CPU emulation as QEMU’s -cpu arg.
    • Validation: Must match qemu-system-x86_64 -cpu help models or be host (uses KVM), defaults to host if unset.
  • platform.volume.<id>.*:
    • Subkeys:
      • type (Required): qcow2 or iso.
      • path (Required): Node-local path (e.g., /tmp/alpine.iso).
      • source (Optional): URL or path for download (e.g., http://host0/isos/alpine.iso will download the alpine.iso from /srv/pxen/http/isos/, if it has been downloaded to there. Otherwise if the remote host has access to the internet, the url can point directly to an iso download: e.g. https://dl-cdn.alpinelinux.org/alpine/v3.21/releases/x86_64/alpine-virt-3.21.3-x86_64.iso).
      • writable (Optional): 1 (read-write) or 0 (read-only), defaults to 0.
      • ephemeral (Optional): 1 (delete on stop/start) or 0 (persist), defaults to 1.
    • Format: <id> is a number (e.g., 0, 1).
    • Purpose: Defines disks as QEMU -drive args.
    • Validation:
      • path must exist on the node (via mesh workload download).
      • type=qcow2: writable toggles readonly.
      • type=iso: writable=1 fails (CDROMs are read-only).
      • ephemeral=0 fails if path exists pre-start.

Network Settings

  • network.<id>.*:
    • Subkeys:
      • type (Required): bridge or nat.
      • bridge (Required for bridge): Bridge name (e.g., br0).
      • mac (Optional): MAC address (e.g., 52:54:00:12:34:56).
    • Format: <id> is a number (e.g., 0).
    • Purpose: Configures NICs as QEMU -netdev and -device args.
    • Validation:
      • type=bridge: bridge must exist on the node (e.g., /sys/class/net/br0/).
      • mac: If unset, generated from uuid, id, and type (e.g., 52:54:00:xx:xx:xx).
      • Uses virtio-net-pci device.

Runtime Settings

  • runtime.boot:
    • Format: Comma-separated list (e.g., 1,0,n0).
    • Purpose: Sets boot order—numbers reference platform.volume.<id> or network.<id> (with n prefix).
    • Validation: Must match existing volume/network IDs or fail. Unset defaults to first volume (c) or network (n).
  • runtime.console.*:
    • Subkeys:
      • type (Optional): serial-tcp, serial-socket, vnc, defaults to serial-tcp.
      • id (Optional for serial-tcp, required for vnc): Integer (e.g., 5).
    • Purpose: Configures console access.
    • Validation:
      • serial-tcp: Port 7900 + id (e.g., 7905), must be free.
      • serial-socket: Uses /tmp/pxen/<uuid>/serial.sock.
      • vnc: Port 5900 + id (e.g., 5905), must be free.

Example Config

/var/pxen/monoliths/qemutest1.conf:

name=qemutest1
uuid=qweflmqwe23
platform.memory.size=4G
platform.cpu.threads=2
platform.cpu.mode=host
platform.volume.0.source=http://host0/isos/alpine-virt-3.21.3-x86_64.iso
platform.volume.0.type=iso
platform.volume.0.path=/tmp/alpine.iso
network.0.type=bridge
network.0.bridge=br0
runtime.console.type=vnc
runtime.console.id=5
  • 4GB RAM, 2 vCPUs, Alpine ISO, bridged to br0, VNC on port 5905.

Notes

Configs are validated on the node—errors (e.g., missing path, invalid threads) halt startup with logs in /tmp/pxen/<uuid>/output.log. Volumes must be downloaded (mesh workload download) before start. Only KVM is supported now; future types may expand options. For bridge setup, see Network Configuration; for node control, see Managing Nodes.

Next, explore Network Config.