# sched-sim

**Repository Path**: gocrane/sched-sim

## Basic Information

- **Project Name**: sched-sim
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SchedSim - Kubernetes Scheduler Simulation Platform

![SchedSim Logo](assets/logo-full.svg)

SchedSim is a comprehensive simulation and testing platform designed for Kubernetes scheduling teams. It enables full-cycle verification of scheduler plugins (kube-scheduler, crane-scheduler, descheduler, pooling-scheduler), covering functional correctness, algorithm effectiveness, performance benchmarking, and component coordination.

## Key Features / 核心功能

*   **Visual Scenario Orchestration**: Design complex testing scenarios using a DAG-based visual editor (React Flow).
*   **Hybrid Simulation Environment**: Supports Kind + KWOK for large-scale node simulation (100s-1000s of nodes) with minimal resource usage.
*   **Cluster Mirroring**: Capture state from production clusters and replay it in a local simulation environment for realistic testing.
*   **Multi-Scheduler Support**: Built-in support for `kube-scheduler`, `crane-scheduler`, `descheduler`, and `pooling-scheduler`.
*   **Chaos Engineering**: Inject faults (node failure, network partition) to verify scheduler resilience.
*   **Comprehensive Reporting**: Generate detailed test reports with metrics, logs, and pass/fail criteria.
*   **Real-time Monitoring**: WebSocket-based real-time execution logs and status updates.

## Quick Start / 快速开始

### Prerequisites

*   **Go**: 1.22+
*   **Node.js**: 20+
*   **Docker**: 20.10+
*   **Kind**: v0.20.0+
*   **KWOK**: v0.5.0+

### Method 1: Local Development (Source)

1.  **Clone the repository**
    ```bash
    git clone https://github.com/gocrane/sched-sim.git
    cd sched-sim
    ```

2.  **Start in Development Mode**
    This starts both the Go backend (with hot reload via `air` if available) and the React frontend (Vite).
    ```bash
    make dev
    ```
    Access the Web UI at `http://localhost:5173` and the API at `http://localhost:8080`.

### Method 2: Docker

1.  **Build the Image**
    ```bash
    make docker
    ```

2.  **Run Container**
    ```bash
    docker run -d -p 8080:8080 --name schedsim schedsim:dev
    ```
    Access the application at `http://localhost:8080`.

### Method 3: Kubernetes (Helm)

1.  **Package Helm Chart**
    ```bash
    make helm-package
    ```

2.  **Install Chart**
    ```bash
    helm install schedsim ./deploy/helm/schedsim
    ```

## Configuration / 配置指南

SchedSim is configured via `configs/schedsim.yaml`. The default configuration includes:

```yaml
server:
  port: 8080
  mode: debug # debug or release

database:
  driver: sqlite # sqlite or postgres
  dsn: "./data/schedsim.db"

environment:
  kindImageRepo: "kindest/node"
  kwokVersion: "v0.5.0"
  maxConcurrentExecutions: 3
```

See [configs/schedsim.yaml](configs/schedsim.yaml) for the full configuration reference.

## Architecture / 系统架构

SchedSim consists of a React+TypeScript frontend and a Go (Gin) backend.

*   **Frontend**: React 18, Ant Design 5, React Flow, ECharts.
*   **Backend**: Go 1.22, Gin Web Framework, GORM.
*   **Infrastructure**: Kind (Kubernetes in Docker), KWOK (Kubernetes WithOut Kubelet).
*   **Storage**: SQLite (default) or PostgreSQL.

For a detailed architecture view, see [System Architecture](design/01-system-architecture.md).

## Usage Guide / 使用指南

### 1. Environment Management
Navigate to **Environments** to create a new simulation cluster. You can choose a "Standard" template (Kind+KWOK) and define the number of simulated nodes (e.g., 100 nodes).

### 2. Scenario Design
Use the **Scenario Editor** to create a test flow:
1.  **Deploy**: Add a step to deploy a workload (Deployment/StatefulSet).
2.  **Assert**: Add a step to wait for "All Pods Scheduled".
3.  **Validate**: Add a step to check "Load Distribution" or "Resource Utilization".

### 3. Execution & Reporting
Run the scenario against your created environment. Watch the real-time logs in the **Execution** view. Once finished, download the PDF/HTML report from the **Reports** center.

## API Overview / API 概览

The backend exposes a RESTful API. Key endpoints include:

*   `POST /api/v1/auth/login`: User authentication.
*   `GET /api/v1/environments`: List managed clusters.
*   `POST /api/v1/executions`: Trigger a new test execution.
*   `GET /api/v1/reports`: Retrieve test reports.
*   `GET /api/v1/ws`: WebSocket connection for real-time updates.

See [internal/api/router/router.go](internal/api/router/router.go) for all defined routes.

## License / 许可证

[MIT License](LICENSE)