Data models: User, Slice, VM, Interface, Link, Network

Cloud Repositorio defines its domain objects in models.py. Each class has a to_dict() method that produces the structure stored in database.yaml and passed between API layers. All dict representations are plain Python types (strings, ints, lists, nested dicts) suitable for YAML serialization.

User

Represents an authenticated user with a quota of VMs and a list of owned slices.

class User:
    def __init__(self, username, password_hash, quota_vms=10):
        self.username = username
        self.password_hash = password_hash
        self.quota_vms = quota_vms
        self.used_vms = 0
        self.slices = []

username

string

required

Unique username. Used as the key in database.yaml under users.

password_hash

string

required

SHA-256 hex digest of the user’s password.

quota_vms

integer

Maximum number of VMs the user may have running simultaneously. Default: 10.

used_vms

integer

Current count of VMs allocated to this user. Incremented by OrchestratorAPI.add_vm_to_slice() and decremented by delete_slice().

slices

integer[]

List of slice_id values owned by this user.

can_create_vms(count) -> bool Returns True if (used_vms + count) <= quota_vms, i.e. there is enough remaining quota to allocate count additional VMs.

user = User("alice", "abc123...", quota_vms=5)
user.used_vms = 4
user.can_create_vms(1)  # True
user.can_create_vms(2)  # False

Flavor

A static registry of VM size definitions. Not intended to be instantiated.

class Flavor:
    FLAVORS = {
        "cirros": {"cores": 1, "ram_gb": 0.5, "disk_gb": 1,
                   "image": "/tmp/vm_images/cirros-0.6.2-x86_64-disk.img"},
        "ubuntu": {"cores": 1, "ram_gb": 0.5, "disk_gb": 2.2,
                   "image": "/tmp/vm_images/focal-server-cloudimg-amd64.img"},
    }

FLAVORS

object

Class-level dict keyed by flavor name. Each value has:

Show flavor spec fields

cores

integer

Number of vCPUs.

ram_gb

float

RAM in gigabytes.

disk_gb

float

Nominal disk size in gigabytes (for reference; actual size is determined by the base image).

image

string

Absolute path to the base image on the manager host.

Flavor.get(flavor_name) -> dict | None Returns the flavor spec dict for flavor_name, or None if the name is not registered.

Flavor.get("cirros")
# {"cores": 1, "ram_gb": 0.5, "disk_gb": 1,
#  "image": "/tmp/vm_images/cirros-0.6.2-x86_64-disk.img"}

Flavor.get("unknown")  # None

Interface

Represents one network interface on a VM.

class Interface:
    def __init__(self, name, vlan_id=None, mac=None, ip_config=None, link_id=None):
        ...

name

string

required

Interface name, e.g. "eth0", "eth1".

vlan_id

integer

OVS VLAN tag assigned to this interface. None means the interface is not yet connected to any VLAN. Set to 400 for management/internet interfaces; set to a slice VLAN ID when a link is created.

mac

string

MAC address in 52:54:00:XX:XX:XX format, generated by DeploymentAPI.generate_unique_macs().

ip_config

object

Present only on eth0 when internet_enabled=True. Structure:

Show ip_config fields

string

Assigned IP address, e.g. "10.60.7.101".

cidr

string

Subnet, e.g. "10.60.7.0/24".

gateway

string

Default gateway, e.g. "10.60.7.1".

link_id

integer

ID of the Link this interface belongs to. None until OrchestratorAPI.create_link() is called.

Link

Represents an L2 connection between two VM interfaces on a shared VLAN.

class Link:
    def __init__(self, link_id, vlan_id, vm1_id, vm1_interface, vm2_id, vm2_interface):
        ...

link_id

integer

required

Sequential identifier within a slice (1, 2, 3, …).

vlan_id

integer

required

OVS VLAN tag allocated from the slice’s VLAN pool.

vm1_id

integer

required

ID of the first VM.

vm1_interface

string

required

Interface name on the first VM, e.g. "eth1".

vm2_id

integer

required

ID of the second VM.

vm2_interface

string

required

Interface name on the second VM, e.g. "eth1".

VM

Represents a virtual machine instance within a slice.

class VM:
    def __init__(self, vm_id, name, owner, worker_ip, vnc_port,
                 interfaces, flavor=None, qcow_image=None):
        self.status = "pending"
        self.pid = None

vm_id

integer

required

Globally unique VM identifier, allocated by Database.get_next_vm_id() (starts at 1000).

name

string

required

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

owner

string

required

Username of the slice owner.

worker_ip

string

required

IP of the worker node where the VM is hosted.

vnc_port

integer

required

Absolute VNC port number (e.g. 5901). Connect with vncviewer {worker_ip}:{vnc_port - 5900}.

interfaces

Interface[]

required

Ordered list of interface objects. Index 0 is always eth0.

flavor

object

The flavor spec dict (see Flavor).

qcow_image

string

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

status

string

Lifecycle state. Transitions: "pending" → "design" (after create_vm_with_qcow) → "running" (after deploy_slice).

pid

string

OS process ID of the QEMU process on the worker. None until deployed.

Network

Represents the network configuration for a VLAN. Created per-link VLAN but not heavily used in the current orchestration flow — VLANManager derives its configuration from link data directly.

class Network:
    def __init__(self, vlan_id, cidr, gateway_ip, dhcp_enabled=False, dhcp_range=None):
        self.status = "pending"

vlan_id

integer

required

OVS VLAN tag.

cidr

string

required

Subnet CIDR, e.g. "192.168.101.0/24".

gateway_ip

string

required

Gateway IP address, e.g. "192.168.101.1".

dhcp_enabled

boolean

Whether dnsmasq DHCP is active for this network. Default: False.

dhcp_range

string

DHCP lease range string, e.g. "192.168.101.10,192.168.101.250". None until DHCP is configured.

status

string

Status of the network configuration. Currently always "pending".

Slice

The top-level container for a tenant’s VM topology.

class Slice:
    def __init__(self, slice_id, owner, topology_type="custom"):
        self.vlan_pool_start = 100 + (slice_id % 100) * 20
        self.vlan_pool_end = self.vlan_pool_start + 19
        self.vlan_pool_used = []
        self.status = "design"

slice_id

integer

required

Unique identifier, allocated by Database.get_next_vm_id() (the same counter as VM IDs).

owner

string

required

Username of the slice owner.

topology_type

string

Descriptor for the topology design, e.g. "custom". Default: "custom".

vlan_pool_start

integer

First VLAN ID in the slice’s private pool. Computed as 100 + (slice_id % 100) * 20.

vlan_pool_end

integer

Last VLAN ID in the pool. Always vlan_pool_start + 19 (20 VLANs per slice).

vlan_pool_used

integer[]

List of VLAN IDs already allocated within this slice.

vms

VM[]

VMs belonging to this slice.

links

Link[]

L2 links defined between VM interfaces.

networks

Network[]

Network objects created alongside links.

status

string

Lifecycle state: "design" or "running".

get_next_vlan() -> int | None Iterates vlan_pool_start…vlan_pool_end and returns the first VLAN ID not in vlan_pool_used, appending it to vlan_pool_used before returning. Returns None when all 20 VLANs are exhausted.

# slice_id=1000 → vlan_pool_start=100, vlan_pool_end=119
s = Slice(1000, "admin")
s.get_next_vlan()  # 100
s.get_next_vlan()  # 101

VLAN pool formula

`slice_id % 100`	`vlan_pool_start`	`vlan_pool_end`
0	100	119
1	120	139
2	140	159
50	1100	1119

Serialized slice example

A complete to_dict() output for a slice with one VM and one link, as stored in database.yaml:

{
  "slice_id": 1000,
  "owner": "admin",
  "topology_type": "custom",
  "vlan_pool_start": 100,
  "vlan_pool_end": 119,
  "vlan_pool_used": [100],
  "status": "running",
  "vms": [
    {
      "vm_id": 1001,
      "name": "vm1",
      "owner": "admin",
      "worker_ip": "10.0.10.1",
      "vnc_port": 5901,
      "status": "running",
      "pid": "4821",
      "qcow_image": "~/vm_images/vm1_img.qcow2",
      "flavor": {
        "cores": 1,
        "ram_gb": 0.5,
        "disk_gb": 1,
        "image": "/tmp/vm_images/cirros-0.6.2-x86_64-disk.img"
      },
      "interfaces": [
        {
          "name": "eth0",
          "vlan_id": 400,
          "mac": "52:54:00:03:e9:00",
          "ip_config": {
            "ip": "10.60.7.101",
            "cidr": "10.60.7.0/24",
            "gateway": "10.60.7.1"
          },
          "link_id": null
        },
        {
          "name": "eth1",
          "vlan_id": 100,
          "mac": "52:54:00:03:e9:01",
          "ip_config": null,
          "link_id": 1
        }
      ]
    },
    {
      "vm_id": 1002,
      "name": "vm2",
      "owner": "admin",
      "worker_ip": "10.0.10.2",
      "vnc_port": 5902,
      "status": "running",
      "pid": "5103",
      "qcow_image": "~/vm_images/vm2_img.qcow2",
      "flavor": {
        "cores": 1,
        "ram_gb": 0.5,
        "disk_gb": 1,
        "image": "/tmp/vm_images/cirros-0.6.2-x86_64-disk.img"
      },
      "interfaces": [
        {
          "name": "eth0",
          "vlan_id": null,
          "mac": "52:54:00:03:ea:00",
          "ip_config": null,
          "link_id": null
        },
        {
          "name": "eth1",
          "vlan_id": 100,
          "mac": "52:54:00:03:ea:01",
          "ip_config": null,
          "link_id": 1
        }
      ]
    }
  ],
  "links": [
    {
      "link_id": 1,
      "vlan_id": 100,
      "vm1_id": 1001,
      "vm1_interface": "eth1",
      "vm2_id": 1002,
      "vm2_interface": "eth1"
    }
  ],
  "networks": []
}

Python API

Data Models

Data models: User, Slice, VM, Interface, Link, Network

User

Flavor

Interface

Link

VM

Network

Slice

Serialized slice example

Build docs developers (and LLMs) love

Python API

Data Models

Documentation Index

​User

​Flavor

​Interface

​Link

​VM

​Network

​Slice

​Serialized slice example

Build docs developers (and LLMs) love

User

Flavor

Interface

Link

VM

Network

Slice

Serialized slice example