README.md

metadata

title: Virtual Machine Placement (Python)
emoji: 👀
colorFrom: gray
colorTo: green
sdk: docker
app_port: 8080
pinned: false
license: apache-2.0
short_description: SolverForge Quickstart for the Vehicle Routing problem

VM Placement Quickstart

A SolverForge quickstart demonstrating constraint-based virtual machine placement optimization.

The Problem

You manage a datacenter with physical servers organized in racks, and must place virtual machines (VMs) onto those servers. Each server has limited CPU cores, memory, and storage capacity.

The challenge: Place all VMs while:

• Never exceeding any server's CPU, memory, or storage capacity
• Keeping database replicas on separate servers (anti-affinity)
• Placing related services together when possible (affinity)
• Minimizing the number of active servers (consolidation)
• Balancing load across active servers

Why Constraint Solving?

With constraints, you describe what a valid placement looks like, not how to compute one. Adding a new business rule (e.g., "GPU workloads need GPU servers") is a single constraint function—not a rewrite of your algorithm.

Quick Start

# 1. Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install -e .

# 3. Run the application
run-app

# 4. Open http://localhost:8080 in your browser

Requirement: JDK 17+ must be installed (solverforge-legacy uses JPype to bridge Python and Java).

Running Tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_constraints.py

Project Structure

vm-placement-fast/
├── src/vm_placement/
│   ├── domain.py          # Server, VM, and VMPlacementPlan
│   ├── constraints.py     # Hard and soft placement constraints
│   ├── solver.py          # SolverForge configuration
│   ├── demo_data.py       # Sample infrastructure and VMs
│   ├── rest_api.py        # FastAPI endpoints
│   └── converters.py      # Domain ↔ REST model conversion
├── tests/
│   └── test_constraints.py  # Unit tests for each constraint
├── static/
│   ├── index.html         # Web UI with rack visualization
│   ├── app.js             # Frontend logic
│   └── config.js          # Advanced settings sliders
└── pyproject.toml         # Dependencies

Constraints

Hard Constraints (must be satisfied)

1. CPU Capacity: Server CPU cannot be exceeded by assigned VMs
2. Memory Capacity: Server memory cannot be exceeded by assigned VMs
3. Storage Capacity: Server storage cannot be exceeded by assigned VMs
4. Anti-Affinity: VMs in the same anti-affinity group (e.g., database replicas) must be on different servers

Soft Constraints (optimize for)

5. Affinity: VMs in the same affinity group (e.g., web tier) should be on the same server
6. Minimize Servers Used: Consolidate VMs onto fewer servers to reduce costs
7. Balance Utilization: Distribute load evenly across active servers
8. Prioritize Placement: Higher-priority VMs should be placed first

API Endpoints

Method	Endpoint	Description
GET	/demo-data	List available datasets
GET	/demo-data/{id}	Load demo data
POST	/demo-data/generate	Generate custom infrastructure
POST	/placements	Submit for optimization
GET	/placements/{id}	Get current solution
GET	/placements/{id}/status	Get solving status
DELETE	/placements/{id}	Stop solving
PUT	/placements/analyze	Analyze placement score

API documentation available at http://localhost:8080/q/swagger-ui

Advanced Settings

The web UI includes configurable sliders for:

• Racks: Number of server racks (1-8)
• Servers per Rack: Servers in each rack (2-10)
• VMs: Number of VMs to place (5-200)
• Solver Time: How long to optimize (5s-2min)

Click "Generate New Data" to create custom scenarios.

VM Placement Concepts

Term	Definition
Server	Physical machine with CPU, memory, and storage capacity
VM	Virtual machine requiring resources from a server
Rack	Physical grouping of servers in a datacenter
Affinity	VMs that should run on the same server
Anti-Affinity	VMs that must run on different servers
Consolidation	Using fewer servers to reduce power/cooling costs

Learn More

• SolverForge Documentation