Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/markitobonito/cloud_repositorio/llms.txt

Use this file to discover all available pages before exploring further.

A slice is the fundamental unit of isolation in Cloud Repositorio — a named container that groups virtual machines and the L2 links between them, backed by a dedicated pool of VLANs. Every resource (VM, link, network) belongs to exactly one slice, and slices are owned by a single user. Isolation is enforced at the VLAN layer: no two slices share VLAN IDs, so traffic cannot leak between tenants at the network level.

​
Slice lifecycle

A slice moves through two states from creation to deployment:
StateTriggered byWhat it means
designcreate_sliceSlice exists in the database. VMs and links can be added but nothing is running.
runningdeploy_sliceVLAN gateways and DHCP namespaces are configured on the network node; all VMs are started on their assigned workers.
Once a slice is running it cannot be deployed again. To rebuild the topology, delete the slice and create a new one.

​
VLAN pool allocation

Each slice is assigned a contiguous block of 20 VLAN IDs at creation time. The block is derived directly from the slice ID: 
vlan_pool_start = 100 + (slice_id % 100) * 20
vlan_pool_end   = vlan_pool_start + 19
For example, slice 1000 gets VLANs 100–119 (100 + (1000 % 100) * 20 = 100), while slice 1001 gets 120–139. Because slice_id % 100 cycles through 0–99, the formula supports up to 100 concurrent slices without any VLAN overlap. VLAN IDs are consumed in order as links are created; get_next_vlan() returns the first unused ID in the pool.

​
User VM quota

Each user account carries a quota_vms ceiling and a used_vms counter. Before every add_vm_to_slice call the orchestrator checks: 
if (user.get("used_vms", 0) + 1) > user.get("quota_vms", 10):
    return False, "Quota exceeded"
Default quotas from database.yaml:
Rolequota_vms
admin10
student6
used_vms is incremented when a VM is added and decremented (via max(0, used_vms - vm_count)) when a slice is deleted.

​
Slice composition

One slice contains:
  • Many VMs — each assigned to a worker node, with one or more network interfaces
  • Many links — each link connects two VM interfaces and consumes one VLAN from the pool
  • Many networks — one Network object per VLAN, carrying CIDR, gateway IP, and DHCP state

​
Sample slice data structure

{
  "slice_id": 1001,
  "owner": "student",
  "topology_type": "custom",
  "status": "running",
  "vlan_pool_start": 120,
  "vlan_pool_end": 139,
  "vlan_pool_used": [120],
  "vms": [
    {
      "vm_id": 1002,
      "name": "router-a",
      "owner": "student",
      "worker_ip": "10.0.10.1",
      "vnc_port": 5902,
      "flavor": {"cores": 1, "ram_gb": 0.5, "disk_gb": 1},
      "qcow_image": "/tmp/vm_images/cirros-1002.qcow2",
      "status": "running",
      "pid": "14823",
      "interfaces": [
        {"name": "eth0", "vlan_id": 400, "mac": "52:54:00:ab:cd:01", "link_id": null},
        {"name": "eth1", "vlan_id": 120, "mac": "52:54:00:ab:cd:02", "link_id": 1}
      ]
    },
    {
      "vm_id": 1003,
      "name": "router-b",
      "owner": "student",
      "worker_ip": "10.0.10.2",
      "vnc_port": 5903,
      "flavor": {"cores": 1, "ram_gb": 0.5, "disk_gb": 1},
      "qcow_image": "/tmp/vm_images/cirros-1003.qcow2",
      "status": "running",
      "pid": "9471",
      "interfaces": [
        {"name": "eth0", "vlan_id": 400, "mac": "52:54:00:ab:cd:03", "link_id": null},
        {"name": "eth1", "vlan_id": 120, "mac": "52:54:00:ab:cd:04", "link_id": 1}
      ]
    }
  ],
  "links": [
    {
      "link_id": 1,
      "vlan_id": 120,
      "vm1_id": 1002,
      "vm1_interface": "eth1",
      "vm2_id": 1003,
      "vm2_interface": "eth1"
    }
  ],
  "networks": [
    {
      "vlan_id": 120,
      "cidr": "192.168.120.0/24",
      "gateway_ip": "192.168.120.1",
      "dhcp_enabled": true,
      "dhcp_range": "192.168.120.10,192.168.120.250",
      "status": "running"
    }
  ]
}
What happens on slice deletion: If the slice is running, the orchestrator stops every VM by sending SIGKILL to the QEMU process on each worker, removes all TAP interfaces from br-int, and tears down VLAN gateways and DHCP namespaces on the network node (ns-dhcp-vlan{vlan_id} deleted, gw_vlan{vlan_id} port removed). Regardless of run state, all per-VM QCOW2 overlay images are deleted from /tmp/vm_images/ on their respective workers. The user’s used_vms counter is reduced by the number of VMs that were in the slice.
Use option “5. View my Slices” in the interactive CLI to inspect the full topology of any slice. The output includes VM IDs, VNC display ports, worker IP assignments, per-interface MAC addresses, VLAN assignments, and link connectivity — useful for verifying the design before deployment or debugging a running slice.

Build docs developers (and LLMs) love

Get started for freeTalk to us