# orin29377053/ray-cluster architecture

> Architecture diagram of the GitHub repository orin29377053/ray-cluster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orin29377053/ray-cluster
- Repository: https://github.com/orin29377053/ray-cluster

## Overview

##### Project type and purpose
- This is an ML-ops/infrastructure project: it automates deployment of a distributed Ray cluster on Minikube via KubeRay, runs Python scripts for parallel compute and YOLOv8 training, and integrates monitoring with Prometheus and Grafana.

##### File structure
- Top-level artifacts:
- Dockerfile, entrypoint.sh, Makefile.example → build & deploy container image
- k8s/ → Kubernetes manifests for RayCluster (ray-cluster.yaml), Ray service (ray-service.yaml), Prometheus & Grafana config
- dashboards/ & upload-dashboard.sh → Grafana dashboard JSONs plus upload tooling
- scripts/ → Python workloads (parallel_compute.py, unstable_task.py, training.py)
- init/download_dataset.py → data initialization
- Patterns: containerized service → deploy via Helm/`kubectl` → Ray head & worker pods → Python tasks submitted via Ray job API → metrics scraped by Prometheus → visualized in Grafana.

##### Key insights from README
- Single Minikube cluster with defined CPU/RAM quotas
- Helm installs for KubeRay operator, Prometheus, Grafana
- RayCluster consists of 1 head node + 3 workers
- Port-forwarding for Ray Dashboard (8265), Grafana (3000), Prometheus (9090)
- Python jobs submitted via `ray job submit` for compute, stability tests, training with Ray Train/Tune and YOLOv8
- Custom metrics via Ray util metrics, scraped by Prometheus → Grafana

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Push Layer
    subgraph "Build & Push Layer"
        Dev["Developer Local Environment"]:::dev
        Dockerfile["Dockerfile"]:::build
        Entrypoint["entrypoint.sh"]:::build
        Makefile["Makefile.example"]:::build
        Dev --> Dockerfile
        Dev --> Entrypoint
        Dev --> Makefile
        Makefile -->|"build & push"| Registry["Docker Hub (IMAGE_NAME)"]:::registry
    end

    %% Container Registry
    subgraph "Container Registry"
        Registry
    end

    %% Minikube Cluster
    subgraph "Minikube Cluster"
        subgraph "Namespace: default"
            Operator["KubeRay Operator (Helm)"]:::infra
            RayClusterCRD["RayCluster (ray-cluster.yaml)"]:::infra
            RayService["Ray Service (ray-service.yaml)"]:::infra
            subgraph "Ray Cluster"
                Head["Ray Head Pod"]:::compute
                Workers["Ray Worker Pods x3"]:::compute
            end
        end
        subgraph "Namespace: prometheus"
            Prom["Prometheus Server"]:::monitor
            Grafana["Grafana Server"]:::monitor
        end
    end

    %% Execution Layer
    subgraph "Execution Layer"
        Parallel["parallel_compute.py"]:::script
        Unstable["unstable_task.py"]:::script
        Training["training.py"]:::script
        Download["download_dataset.py"]:::script
    end

    %% Grafana Dashboards
    subgraph "Grafana Dashboards"
        DataJSON["data_grafana_dashboard.json"]:::dash
        DefaultJSON["default_grafana_dashboard.json"]:::dash
        ServeDeployJSON["serve_deployment_grafana_dashboard.json"]:::dash
        ServeJSON["serve_grafana_dashboard.json"]:::dash
        Upload["upload-dashboard.sh"]:::dash
    end

    %% Interactions
    Registry -->|"pull image"| RayClusterCRD
    Parallel -->|"ray job submit"| Head
    Unstable -->|"ray job submit"| Head
    Training -->|"ray job submit"| Head
    Download -->|"init job"| Head
    Head -->|"metrics endpoint"| Prom
    Workers -->|"metrics endpoint"| Prom
    Prom -->|"data source"| Grafana
    DataJSON --> Upload
    DefaultJSON --> Upload
    ServeDeployJSON --> Upload
    ServeJSON --> Upload
    Upload --> Grafana

    %% Port-Forwarding
    Head -->|"Port:8265"| Dev
    Prom -->|"Port:9090"| Dev
    Grafana -->|"Port:3000"| Dev

    %% Click Events
    click Dockerfile "https://github.com/orin29377053/ray-cluster/tree/main/Dockerfile"
    click Entrypoint "https://github.com/orin29377053/ray-cluster/blob/main/entrypoint.sh"
    click Makefile "https://github.com/orin29377053/ray-cluster/blob/main/Makefile.example"
    click RayClusterCRD "https://github.com/orin29377053/ray-cluster/blob/main/k8s/ray-cluster.yaml"
    click RayService "https://github.com/orin29377053/ray-cluster/blob/main/k8s/ray-service.yaml"
    click Prom "https://github.com/orin29377053/ray-cluster/blob/main/k8s/prometheus-config.yaml"
    click Grafana "https://github.com/orin29377053/ray-cluster/blob/main/k8s/grafana-config.yaml"
    click DataJSON "https://github.com/orin29377053/ray-cluster/blob/main/dashboards/data_grafana_dashboard.json"
    click DefaultJSON "https://github.com/orin29377053/ray-cluster/blob/main/dashboards/default_grafana_dashboard.json"
    click ServeDeployJSON "https://github.com/orin29377053/ray-cluster/blob/main/dashboards/serve_deployment_grafana_dashboard.json"
    click ServeJSON "https://github.com/orin29377053/ray-cluster/blob/main/dashboards/serve_grafana_dashboard.json"
    click Upload "https://github.com/orin29377053/ray-cluster/blob/main/upload-dashboard.sh"
    click Parallel "https://github.com/orin29377053/ray-cluster/blob/main/scripts/parallel_compute.py"
    click Unstable "https://github.com/orin29377053/ray-cluster/blob/main/scripts/unstable_task.py"
    click Training "https://github.com/orin29377053/ray-cluster/blob/main/scripts/training.py"
    click Download "https://github.com/orin29377053/ray-cluster/blob/main/init/download_dataset.py"
    click Registry "https://github.com/orin29377053/ray-cluster/tree/main/images/"

    %% Styles
    classDef build fill:#FFEB3B,stroke:#333,stroke-width:1px
    classDef registry fill:#FFE082,stroke:#333,stroke-width:1px
    classDef infra fill:#B0BEC5,stroke:#333,stroke-width:1px
    classDef compute fill:#90CAF9,stroke:#333,stroke-width:1px
    classDef monitor fill:#A5D6A7,stroke:#333,stroke-width:1px
    classDef script fill:#FFF59D,stroke:#333,stroke-width:1px
    classDef dash fill:#FFCC80,stroke:#333,stroke-width:1px
    classDef dev fill:#CFD8DC,stroke:#333,stroke-width:1px
```
