DeploymentAPI and QCOWManager: QCOW2 image setup

DeploymentAPI orchestrates VM object creation: it assigns VNC ports, generates MAC addresses, creates network interface objects, and delegates QCOW2 image creation to QCOWManager. It does not communicate directly with worker nodes beyond what QCOWManager needs during image provisioning.

DeploymentAPI

`init(remote_executor, base_image_path=None)`

remote_executor

RemoteExecutor

required

A RemoteExecutor instance used by the internal QCOWManager to check for and copy base images on worker nodes.

base_image_path

string

Optional override for the base image path. When None, the path is taken from the flavor specification at VM creation time.

The constructor initialises vnc_port_counter = 5900. The counter is incremented before assignment, so the first VM created gets port 5901.

from remote_executor import RemoteExecutor
from deployment_api import DeploymentAPI

executor = RemoteExecutor()
deployment = DeploymentAPI(executor)

`generate_unique_macs(vm_id, count=3)` → `list[str]`

Generates a list of deterministic MAC addresses derived from vm_id.

vm_id

integer

required

The VM’s numeric identifier. Used to populate bytes 4 and 5 of the MAC address.

count

integer

default:"3"

Number of MAC addresses to generate. Each address differs only in the last byte (the interface index).

MAC formula

52:54:00:{(vm_id >> 8) & 0xFF:02x}:{vm_id & 0xFF:02x}:{i:02x}

Where i is the zero-based interface index. Example for vm_id=1001 (0x3E9)

Index	MAC address
0	`52:54:00:03:e9:00`
1	`52:54:00:03:e9:01`
2	`52:54:00:03:e9:02`

macs = deployment.generate_unique_macs(vm_id=1001, count=3)
# ["52:54:00:03:e9:00", "52:54:00:03:e9:01", "52:54:00:03:e9:02"]

`create_vm_with_qcow(slice_id, vm_id, vm_name, owner, worker_ip, flavor, data_interfaces_count, internet_enabled=False)` → `(bool, VM | None)`

Creates a VM object with all interfaces and a QCOW2 backing image on the target worker.

slice_id

integer

required

Slice this VM belongs to (informational; not stored on the VM object itself).

vm_id

integer

required

Unique VM identifier, used for MAC generation and as part of the TAP device name at launch time.

vm_name

string

required

Human-readable name, used as the QCOW2 image filename prefix.

owner

string

required

Username of the slice owner, stored on the VM object.

worker_ip

string

required

IP address of the worker node where the QCOW2 image is created and the VM will later run.

flavor

object

required

Flavor specification dict with keys cores (int), ram_gb (float), disk_gb (float), and image (str — base image path). Use Flavor.get("cirros") or Flavor.get("ubuntu") to obtain a valid dict.

data_interfaces_count

integer

required

Number of data interfaces (eth1…ethN) to create in addition to eth0.

internet_enabled

boolean

default:"false"

When True, eth0 is assigned vlan_id=400 and an ip_config dict with IP 10.60.7.{100 + vm_id % 100}. When False, eth0 has vlan_id=None and ip_config=None.

Interface creation summary

Interface	`vlan_id`	`ip_config`	`link_id`
`eth0`	400 or `None`	Set if internet, else `None`	—
`eth1`…`ethN`	`None`	`None`	`None`

Returns

(True, VM) — VM object with status="design" and the QCOW2 image path populated.
(False, None) — QCOW2 image creation failed or an unexpected exception occurred.

from models import Flavor

flavor_spec = Flavor.get("cirros")
success, vm = deployment.create_vm_with_qcow(
    slice_id=1000,
    vm_id=1001,
    vm_name="vm1",
    owner="admin",
    worker_ip="10.0.10.1",
    flavor=flavor_spec,
    data_interfaces_count=1,
    internet_enabled=True,
)
# vm.vnc_port    → 5901
# vm.qcow_image  → "~/vm_images/vm1_img.qcow2"
# vm.status      → "design"

`delete_vm_dict(vm_dict)` → `bool`

Deletes the QCOW2 image associated with a serialized VM dict.

vm_dict

object

required

A dict as produced by VM.to_dict(). The keys qcow_image and worker_ip are used; if qcow_image is None or absent the call is a no-op and returns True.

Returns True on success or when there is no image to delete. False on exception.

deployment.delete_vm_dict(vm.to_dict())

QCOWManager

QCOWManager manages the QCOW2 image lifecycle on remote worker nodes. It is constructed automatically inside DeploymentAPI.__init__ and is not typically used directly.

`init(remote_executor, base_dir="~/vm_images")`

remote_executor

RemoteExecutor

required

Used for SSH commands to the worker node.

base_dir

string

default:"~/vm_images"

Directory on the worker where base images and per-VM images are stored.

`create_backing_image(worker_ip, vm_name, base_image_path, vlan_ids)` → `(bool, str | None)`

Ensures the base image is present on the worker, then creates a thin-provisioned QCOW2 overlay.

worker_ip

string

required

Target worker node IP.

vm_name

string

required

Used to name the overlay image {vm_name}_img.qcow2.

base_image_path

string

required

Full path to the base image on the manager host, e.g. /tmp/vm_images/cirros-0.6.2-x86_64-disk.img. The basename is derived with os.path.basename().

vlan_ids

array

Currently unused by the method body. Reserved for future use.

Execution steps

Check for base image

Runs test -f ~/vm_images/{base_filename} on the worker.

Copy if missing

If the base image is absent, runs scp {base_image_path} ubuntu@{worker_ip}:~/vm_images/ from the manager host. Timeout: 60 seconds.

Create overlay

Runs qemu-img create -f qcow2 -b {base_filename} -F qcow2 {vm_name}_img.qcow2 inside ~/vm_images/ on the worker.

Returns

(True, "~/vm_images/{vm_name}_img.qcow2") on success.
(False, None) if the SCP transfer or qemu-img command fails.

ok, path = qcow_mgr.create_backing_image(
    worker_ip="10.0.10.1",
    vm_name="vm1",
    base_image_path="/tmp/vm_images/cirros-0.6.2-x86_64-disk.img",
    vlan_ids=[],
)
# ok   → True
# path → "~/vm_images/vm1_img.qcow2"

`delete_image(worker_ip, image_path)` → `bool`

Removes a QCOW2 image from the worker.

worker_ip

string

required

Worker node IP.

image_path

string

required

Path to the image on the worker, e.g. "~/vm_images/vm1_img.qcow2".

Executes rm -f {image_path} via SSH. Returns True on success, False on exception.

qcow_mgr.delete_image("10.0.10.1", "~/vm_images/vm1_img.qcow2")

Python API

Data Models

DeploymentAPI and QCOWManager: QCOW2 image setup

DeploymentAPI

`init(remote_executor, base_image_path=None)`

`generate_unique_macs(vm_id, count=3)` → `list[str]`

`create_vm_with_qcow(slice_id, vm_id, vm_name, owner, worker_ip, flavor, data_interfaces_count, internet_enabled=False)` → `(bool, VM | None)`

`delete_vm_dict(vm_dict)` → `bool`

QCOWManager

`init(remote_executor, base_dir="~/vm_images")`

`create_backing_image(worker_ip, vm_name, base_image_path, vlan_ids)` → `(bool, str | None)`

`delete_image(worker_ip, image_path)` → `bool`

Build docs developers (and LLMs) love

Python API

Data Models

Documentation Index

​DeploymentAPI

​__init__(remote_executor, base_image_path=None)

​generate_unique_macs(vm_id, count=3) → list[str]

​create_vm_with_qcow(slice_id, vm_id, vm_name, owner, worker_ip, flavor, data_interfaces_count, internet_enabled=False) → (bool, VM | None)

​delete_vm_dict(vm_dict) → bool

​QCOWManager

​__init__(remote_executor, base_dir="~/vm_images")

​create_backing_image(worker_ip, vm_name, base_image_path, vlan_ids) → (bool, str | None)

​delete_image(worker_ip, image_path) → bool

Build docs developers (and LLMs) love

DeploymentAPI

`init(remote_executor, base_image_path=None)`

`generate_unique_macs(vm_id, count=3)` → `list[str]`

`create_vm_with_qcow(slice_id, vm_id, vm_name, owner, worker_ip, flavor, data_interfaces_count, internet_enabled=False)` → `(bool, VM | None)`

`delete_vm_dict(vm_dict)` → `bool`

QCOWManager

`init(remote_executor, base_dir="~/vm_images")`

`create_backing_image(worker_ip, vm_name, base_image_path, vlan_ids)` → `(bool, str | None)`

`delete_image(worker_ip, image_path)` → `bool`