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.

This quickstart walks you through creating and deploying a slice with two VMs connected over a private VLAN using the Cloud Repositorio CLI. By the end, you will have two running virtual machines that can reach each other over an isolated L2 network segment on your cluster.
1

Prerequisites

Before you start, make sure the following are in place:
  • SSH key access to each worker node as ubuntu. The default cluster uses [email protected], [email protected], and [email protected]. All three nodes must be reachable without a password prompt: 
    ssh [email protected]
ssh [email protected]
ssh [email protected]
  • Python 3 with the PyYAML package installed on the orchestrator machine: 
    pip install pyyaml
  • QEMU/KVM installed and working on each worker node.
  • Open vSwitch (OVS) running on the network node (10.0.10.3), with a bridge named br-int.
  • Base VM images present at /tmp/vm_images/ on every worker:
    • cirros-0.6.2-x86_64-disk.img
    • focal-server-cloudimg-amd64.img
2

Start the manager

From the project root, run:
python main.py
On startup, the orchestrator backs up database.yaml, then runs WorkerDiscovery against all three nodes. Discovery runs nproc, free -g, and df /tmp over SSH to populate each worker’s resource specs. Once discovery completes, the CLI drops into the login prompt.
2026-05-18 10:00:01 - INFO - Worker 10.0.10.1: {'ip': '10.0.10.1', 'max_cores': 4, ...}
2026-05-18 10:00:02 - INFO - Worker 10.0.10.2: {'ip': '10.0.10.2', 'max_cores': 4, ...}
2026-05-18 10:00:03 - INFO - Worker 10.0.10.3: {'ip': '10.0.10.3', 'max_cores': 4, ...}

==================================================
  SLICE MANAGER - LOGIN
==================================================
Username:
3

Log in

Enter your credentials at the login prompt. The database.yaml file ships with two pre-configured accounts. The password for both is the SHA-256 hash of the string admin:
UsernamePasswordVM quota
adminadmin10 VMs
studentadmin6 VMs
Username: admin
Password: admin

Welcome, admin!
After a successful login you are taken to the main menu:
==================================================
  MAIN MENU
==================================================
1. View quota and resources
2. Create Slice
3. Add VM to Slice
4. Create Link between VMs
5. View my Slices
6. Deploy Slice
7. Delete Slice
8. Logout
4

Create a slice

Choose 2. Create Slice and enter a name for your slice:
Choice: 2

Slice name: my-first-slice

✅ Slice created! ID: 1000
The orchestrator assigns the next available ID from database.yaml (starting at 1000) and allocates a VLAN pool of 20 IDs for this slice. Make a note of the slice ID — you will use it in the next steps.
5

Add VMs to the slice

Choose 3. Add VM to Slice for each VM you want to create. Add the first VM:
Choice: 3

Slice ID: 1000
VM name: vm-a

Available flavors:
1. cirros (1 core, 0.5GB RAM, 1GB disk)
2. ubuntu (1 core, 0.5GB RAM, 2.2GB disk)
Choose flavor (1-2): 1

Number of data interfaces (eth1, eth2, ...): 1
Enable internet access (eth0 in VLAN 400)? (y/n): n

✅ VM added! ID: 1001, VNC: 5901, Flavor: cirros
Repeat the process to add a second VM:
Choice: 3

Slice ID: 1000
VM name: vm-b

Available flavors:
1. cirros (1 core, 0.5GB RAM, 1GB disk)
2. ubuntu (1 core, 0.5GB RAM, 2.2GB disk)
Choose flavor (1-2): 1

Number of data interfaces (eth1, eth2, ...): 1
Enable internet access (eth0 in VLAN 400)? (y/n): n

✅ VM added! ID: 1002, VNC: 5902, Flavor: cirros
VMs are assigned to workers in round-robin order. Each VM gets a management interface (eth0) and one data interface per additional interface you specified (eth1, eth2, etc.).
6

Create a link between VMs

Choose 4. Create Link between VMs to connect vm-a and vm-b over a private VLAN:
Choice: 4

Slice ID: 1000

Available VMs and interfaces:
  VM 1001: vm-a
    - eth1 (unconnected)
  VM 1002: vm-b
    - eth1 (unconnected)

First VM ID: 1001
First VM interface (e.g., eth1): eth1
Second VM ID: 1002
Second VM interface (e.g., eth1): eth1

✅ Link created! VLAN: 100
A VLAN ID is drawn automatically from the slice’s pool. The orchestrator records the link and tags both interfaces with the assigned VLAN ID. No physical network changes happen yet — those are applied during deployment.
7

Deploy the slice

Choose 6. Deploy Slice to bring the slice up:
Choice: 6

Slice ID to deploy: 1000
The orchestrator:
  1. Configures an OVS VLAN gateway and dnsmasq DHCP namespace on 10.0.10.3 for each link.
  2. Launches each VM over SSH on its assigned worker — creating TAP interfaces, tagging them with the correct VLAN, and starting qemu-system-x86_64 as a daemon.
  3. Updates database.yaml with the running status and QEMU PID for each VM.
2026-05-18 10:01:00 - INFO - Configuring VLAN 100 for Link 1
2026-05-18 10:01:02 - INFO - Deploying VM 1001 on 10.0.10.1
2026-05-18 10:01:05 - INFO - VM 1001 started with PID 23841
2026-05-18 10:01:05 - INFO - Deploying VM 1002 on 10.0.10.2
2026-05-18 10:01:08 - INFO - VM 1002 started with PID 19204
2026-05-18 10:01:08 - INFO - Slice 1000 deployed successfully

Slice deployed successfully
VNC access to each VM is available at worker_ip:vnc_port immediately after deployment. For example, if vm-a was placed on 10.0.10.1 with VNC port 5901, connect with any VNC client to 10.0.10.1:5901. The base VNC port is 5900; each VM increments from there based on its VM ID.
Press Ctrl+C at any time while the manager is running to trigger a graceful rollback. The SIGINT handler calls delete_slice() on the active slice, kills all QEMU processes on every worker, tears down VLAN namespaces on the network node, and removes local temporary files before exiting.

Build docs developers (and LLMs) love

Get started for freeTalk to us