cloudsim 1.0.2

Local-first cloud infrastructure simulator (Flask API + CLI).

CloudSim

CloudSim is a local-first cloud infrastructure simulator with a CLI and backend server.

It is built to help you learn cloud concepts by creating VMs, load balancers, traffic simulations, and per-VM databases on your own machine.

Cloud Architect Academy

Want a guided course version? Visit the academy:

Quickstart

Install:

pip install cloudsim

Create a workspace:

cloudsim config init --workspace ./cloudsim-workspace

Set the workspace for your current terminal if needed:

Windows PowerShell:

$env:CLOUDSIM_WORKSPACE = (Resolve-Path .\cloudsim-workspace).Path

macOS/Linux:

export CLOUDSIM_WORKSPACE="$(pwd)/cloudsim-workspace"

On Windows, you can also set CLOUDSIM_WORKSPACE from the Environment Variables screen in the Start menu search.

If you save CLOUDSIM_WORKSPACE as a user environment variable, you only need to set it once.

Start the backend server:

cloudsim-server

If cloudsim-server is not available in your shell, use:

python -m cloudsim.app

Leave that terminal open.

In a second terminal, check health:

cloudsim health

Create your first VM:

cloudsim vm create --name vm1 --region us-central1 --machine-type e2-micro --image ubuntu --backend-profile-id python-fastapi

What cloudsim-server Does

cloudsim-server starts the CloudSim backend API.

• Default URL: http://127.0.0.1:5000
• Keep it running while you use cloudsim commands in another terminal
• Commands like vm create, state, lb create, simulate, expose, and call talk to this backend
• If the launcher is not available in your shell, use python -m cloudsim.app

Quick check:

cloudsim health

Your First End-to-End Flow

Start the backend:

cloudsim-server

Then in another terminal:

cloudsim health
cloudsim vm create --name vm1 --region us-central1 --machine-type e2-micro --image ubuntu --backend-profile-id python-fastapi

Use the VM id returned by the create command:

cloudsim expose <vmId>
cloudsim call <vmId> /health

SSH into the VM workspace:

cloudsim ssh <vmId>

Use the VM id, not the VM name.

Create a script-based demo VM:

cloudsim vm create --name demo-vm --region us-central1 --machine-type e2-micro --image ubuntu --backend-profile-id python-fastapi --runtime-mode python_script --script-path scripts/sample_app.py

Workspace

CloudSim stores its runtime state in a workspace directory, not inside the installed package.

cloudsim config init --workspace ./cloudsim-workspace creates:

• <workspace>/.env
• ~/.cloudsim/config.json

If you do not want a global default workspace file:

cloudsim config init --workspace ./cloudsim-workspace --no-default

Workspace resolution order:

1. CLOUDSIM_WORKSPACE
2. ~/.cloudsim/config.json
3. current working directory

Files created in the workspace:

• <workspace>/.cloudsim/simulation.db
• <workspace>/.cloudsim/sql_service.db
• <workspace>/vms/<vmId>/vm_state.db
• <workspace>/vms/<vmId>/vm_sqlite.db
• <workspace>/autoscale-vms/<vmId>/...

Common Commands

Check health:

cloudsim health

Show current state:

cloudsim state

Create a VM:

cloudsim vm create --name vm1 --region us-central1 --machine-type e2-micro --image ubuntu --backend-profile-id python-fastapi

List VMs:

cloudsim vm list

Open a VM shell:

cloudsim ssh <vmId>

Use the VM id returned by cloudsim vm create.

Create a load balancer:

cloudsim lb create --name lb1 --type HTTP(S) --region global --backend-vm-id <vmId>

Run a traffic simulation:

cloudsim simulate --lb-id <lbId> --endpoint-key "GET /health" --requests 500

Provision per-VM SQLite:

cloudsim sql provision --vm-id <vmId>
cloudsim sql execute --vm-id <vmId> --mode local --query "CREATE TABLE items(id INTEGER PRIMARY KEY, name TEXT)"
cloudsim sql execute --vm-id <vmId> --mode local --query "SELECT id,name FROM items"

Optional Real PostgreSQL Setup

If real PostgreSQL is configured and reachable, CloudSim can provision real database spaces. Otherwise it falls back to per-VM SQLite.

Set these in <workspace>/.env:

• CLOUDSIM_PG_HOST=127.0.0.1
• CLOUDSIM_PG_PORT=5432
• CLOUDSIM_PG_ADMIN_USER=postgres
• CLOUDSIM_PG_ADMIN_PASSWORD=pg123
• CLOUDSIM_PG_ADMIN_DB=postgres

Then use:

cloudsim sql real-status
cloudsim sql real-provision --vm-id <vmId>
cloudsim sql real-connect --vm-id <vmId>

Troubleshooting

If you see:

Unable to reach backend at http://127.0.0.1:5000

then the backend is not running yet. Start it with:

cloudsim-server

If the workspace is not being picked up, set CLOUDSIM_WORKSPACE in your terminal or add it from the Windows Environment Variables search screen.

If port 5000 is busy, run the backend manually on another port:

python -c "from cloudsim.app import app; app.run(host='127.0.0.1', port=5052, debug=False)"

Then point the CLI to that port:

cloudsim --base-url http://127.0.0.1:5052 health

Advanced

Most users do not need these, but they are available:

• Start backend via Python module: python -m cloudsim.app
• Run CLI via Python module: python -m cloudsim.cli_services.runtime --help
• Open a VM shell: cloudsim ssh <vmId>

If you installed with pip and cloudsim is not found, use a virtualenv or add your Python scripts directory to PATH.

License

MIT (see LICENSE).