COUBES

Comparing container orchestration schedulers today requires either costly real-cluster experiments or reimplementing scheduling logic inside a simulator. COUBES (Container Orchestration Universal Benchmark for Evaluating Schedulers) eliminates both: it connects unmodified scheduler binaries to CloudSim 7G through a lightweight middleware implementing a simulated Kubernetes API server. This enables reproducible, multi-metric comparison — spanning energy efficiency, time-to-completion, and resource consolidation — on a single machine, without requiring a real or emulated cluster.

This repository contains the proof-of-concept implementation, developed as part of an MSci Project (2024–2026).

Overview

COUBES delegates scheduling decisions to unmodified Kubernetes scheduler binaries via a lightweight middleware layer. Instead of re-implementing scheduling logic inside CloudSim, the adapter implements a fake Kubernetes API server that real schedulers connect to directly — no cluster infrastructure (etcd, kube-apiserver, KWOK) is required.

• CloudSim VMs are exposed as Kubernetes Nodes
• CloudSim Cloudlets are exposed as Kubernetes Pods
• The scheduler makes placement decisions via the standard binding API
• Results are mapped back into CloudSim for simulation to proceed

Currently supported schedulers:

• kube-scheduler (Least Allocated / Most Allocated profiles)
• Volcano (bin-packing, queue resource management, gang scheduling)

How to Run

Prerequisites: Go, Docker (for scheduler containers), Java JDK 21, Maven.

You should also clone CloudSim 7.0.1 and install it locally: mvn clean install -DskipTests within the CloudSim repository.

Using run_test.sh (recommended)

# Test mode — built-in round-robin scheduler, no Docker needed
./run_test.sh --test-mode org.example.testSuite.Fragmentation_Test

# kube-scheduler (Least Allocated — default)
./run_test.sh org.example.testSuite.Fragmentation_Test

# kube-scheduler (Most Allocated — bin-packing)
./run_test.sh --scheduler=most-allocated org.example.testSuite.Fragmentation_Test

# Volcano scheduler
./run_test.sh --volcano org.example.testSuite.Queue_Priority_Test

The script handles compilation, infrastructure startup, hang detection, and auto-recovery. Use --no-compile to skip rebuilding, --no-filter for full output.

Run all tests

./run_all_tests.sh              # kube-scheduler
./run_all_tests.sh --volcano    # Volcano

Compare schedulers

./compare_schedulers.sh Fragmentation_Test

Produces timestamped CSVs in results/ with raw metrics and relative scores.

For manual startup, debugging, and troubleshooting, see docs/running-and-debugging.md.

Structure

├── src/main/java/org/example/
│   ├── kubernetes_broker/     # Custom CloudSim broker + datacenter + VM classes
│   ├── metrics/               # SimulationMetrics, PerformanceMetrics
│   └── testSuite/             # Benchmark test scenarios
├── k8s-cloudsim-adapter/      # Go middleware (fake K8s API server)
├── kube-scheduler/            # Docker config for kube-scheduler
├── volcano-scheduler/         # Docker config for Volcano scheduler
├── docs/                      # Documentation (see below)
├── run_test.sh                # Single-test runner with infra management
├── run_all_tests.sh           # Full test suite runner
└── compare_schedulers.sh      # Scheduler comparison tool

Documentation

The following documents are available for readers and collaborators to get familiar with the codebase:

Document	Contents
Architecture	High-level design, component overview, design decisions
End-to-End Workflow	Data flow diagram, step-by-step explanation, rescheduling loop, code reading guide
Simulated API Reference	All 46 endpoints exposed by the middleware
Running and Debugging	Manual startup, common errors, log reading, troubleshooting
Volcano	Volcano-specific features, configuration, extending

You may also read the Kiro steering files manually at .kiro/steering/ — although these are written to provide context for the agentic AI rather than for human readers.

Test Scenarios

Test	What it measures
Fragmentation_Test	Bin-packing under mixed workloads
Overload_Comparison_Test	Multi-queue + gang scheduling under sustained load
Gang_Scheduling_Test	Atomic all-or-nothing scheduling
Queue_Priority_Test	Weighted resource sharing between queues
Scheduler_Scalability_Test	Scheduling latency at scale (5,000–100,000 pods)
Performance_vs_Efficiency_Test	Energy vs throughput tradeoff

See src/main/java/org/example/testSuite for the full list.

Architecture

AI Usage

Development of this PoC was assisted by Claude (Anthropic) via Kiro CLI. AI was used for implementation tasks and debugging; all architectural and design decisions were made by the authors. Steering files in .kiro/ provide context for AI-assisted continuation of the project.