# longhorn/kbench architecture

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

- Interactive diagram: https://gitdiagram.com/longhorn/kbench
- Repository: https://github.com/longhorn/kbench

## Overview

##### Project type and purpose
- KBench is an open-source benchmarking tool focused on storage (local and distributed) and Kubernetes.
- It orchestrates FIO workloads (shell scripts + .fio job definitions), packages them in containers, deploys them as Kubernetes workloads, and exports results via logs and a Prometheus-style metric-exporter.

##### File structure
Top-level:
- Dockerfile.dapper, Makefile – CI/build orchestration
- deploy/ – Kubernetes YAMLs for single-volume and comparison benchmarks
- fio/ – all FIO job files (.fio), wrapper scripts (run.sh, parse.sh, cmp_run.sh, etc.)
- metric-exporter/ – Go module implementing a HTTP service that collects FIO results and serves Prometheus metrics
- package/ – Dockerfile used to build the final container image
- scripts/ – reusable CI/build/package/validate/versioning scripts

##### Extract insights from the README
- Describes two primary modes: single-volume and comparison benchmarks.
- Shows usage patterns: local binary, Docker container, or Kubernetes deployment.
- Emphasizes FIO metrics (IOPS, bandwidth, latency, CPU idleness) and how to interpret them.
- Mentions default storage-class usage and configurable parameters (SIZE, CPU_IDLE_PROF, storage class names).

##### Main components
A. Build & CI subsystem
– Source code (Git repo)
– CI scripts (scripts/ci) invoking Dapper (Dockerfile.dapper) and Makefile
– Result: kbench container image (package/Dockerfile) pushed to registry
B. FIO Runner
– Container entrypoint (scripts/entry or fio/run.sh inside image)
– FIO job files (fio/*.fio) and shell wrappers (fio/run.sh, cmp_run.sh, parse.sh, common-include.fio)
– Mounted test volume (host path, PV/PVC in Kubernetes)
– Produces JSON outputs and summary logs
C. Metric-Exporter Service
– Go HTTP server (metric-exporter/main.go)
– Registry and metrics packages (metric-exporter/registry, metrics, types)
– Scrapes or ingests FIO JSON outputs, exposes Prometheus endpoint
D. Kubernetes Deployment
– deploy/fio.yaml (Job/Pod spec for single-volume)
– deploy/fio-cmp.yaml (for comparison)
– Volume Claims (PVCs) and storage classes (local-path, Longhorn, etc.)
– Pods run kbench container, sidecar or init-container for metric-exporter (if used)
E. External Systems
– Prometheus (scrapes metric-exporter)
– kubectl / user (fetches logs via kubectl logs -l kbench=fio)
– Optional Grafana for dashboards

##### Relationships and data flows
- CI → Docker registry: build & publish image
- Kubernetes API → deploys FIO Job pods using images
- FIO Runner container → runs FIO jobs against test volume → writes JSON + logs
- Metric-Exporter → reads FIO JSON or listens on a local port → exposes Prometheus metrics
- Prometheus → scrapes metric-exporter → stores time-series data
- User → kubectl logs and/or Grafana dashboards

##### Important architectural patterns & design principles
- Containerization: each component (FIO runner, metric-exporter) packaged in Docker
- Declarative deploy: Kubernetes manifests define everything from PVCs to Jobs
- Modular scripting: separate job definitions (.fio) and wrappers (shell scripts)
- Micro-service style: metric-exporter is a standalone HTTP service
- CI/CD pipeline: Dapper + Makefile + scripts automate build, validation, versioning

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Subsystem
    subgraph "Build & CI Subsystem" 
        direction TB
        Git["Git Repo"]:::external
        CIScripts["CI Scripts (scripts/ci/*)"]:::build
        Dapper["Dockerfile.dapper"]:::build
        Make["Makefile"]:::build
        PackageScripts["Packaging Scripts\n(scripts/build,\n scripts/package,\n scripts/validate,\n scripts/version)"]:::build
        Git --> CIScripts
        CIScripts --> Dapper
        CIScripts --> Make
        CIScripts --> PackageScripts
        Dapper --> BuildImage
        Make --> BuildImage
        PackageScripts --> BuildImage
    end

    BuildImage["kbench Container Image"]:::container
    BuildImage -->|push| Registry["Container Registry"]:::external

    %% Kubernetes Deployment
    subgraph "Kubernetes Cluster" 
        direction TB
        API["Kubernetes API"]:::k8s
        API --> FioJobPod
        subgraph "FIO Job Pod" 
            direction TB
            FioJobPod["Pod: kbench"]:::k8s
            PVC["PVC: test-volume"]:::k8s
            FioRunner["FIO Runner Container"]:::container
            MetricExporterC["Metric-Exporter Sidecar"]:::container
            FioJobPod --> PVC
            FioJobPod --> FioRunner
            FioJobPod --> MetricExporterC

            subgraph "FIO Runner Container FS"
                direction TB
                Entry["scripts/entry"]:::file
                RunSh["fio/run.sh"]:::file
                CmpRun["fio/cmp_run.sh"]:::file
                Parse["fio/parse.sh\nfio/cmp_parse.sh"]:::file
                Common["fio/common-include.fio"]:::file
                BW["fio/bw-include.fio"]:::file
                IOPS["fio/iops-include.fio"]:::file
                Lat["fio/lat-include.fio"]:::file
                JobDefs["*.fio job files"]:::file
                Entry --> RunSh
                Entry --> CmpRun
                RunSh --> Common
                CmpRun --> Common
                Parse --> Common
                Common --> BW
                Common --> IOPS
                Common --> Lat
                Common --> JobDefs
            end

            FioRunner --> JsonOut["JSON Outputs + Logs"]:::artifact
            JsonOut --> MetricExporterC
        end
    end

    %% Metric Exporter Service Internals
    subgraph "Metric-Exporter Service Code" 
        direction TB
        Main["main.go"]:::file
        GoMod["go.mod"]:::file
        GoSum["go.sum"]:::file
        MetricsPkg["metrics/metrics.go"]:::file
        RegistryPkg["registry/registry.go"]:::file
        TypesConst["types/constants.go"]:::file
        Types["types/types.go"]:::file
        Main --> RegistryPkg
        Main --> MetricsPkg
        Main --> TypesConst
        Main --> Types
        Main --> GoMod
        Main --> GoSum
    end

    MetricExporterC -->|"runs HTTP Server"| Main
    Main -->|"exposes /metrics"| Prometheus["Prometheus"]:::external

    %% External User Interaction
    User["User"]:::external
    User -->|"kubectl logs"| JsonOut
    User -->|"Grafana dashboards"| Prometheus

    %% Click Events
    click Dapper "https://github.com/longhorn/kbench/blob/main/Dockerfile.dapper"
    click Make "https://github.com/longhorn/kbench/tree/main/Makefile"
    click CIScripts "https://github.com/longhorn/kbench/tree/main/scripts/ci"
    click PackageScripts "https://github.com/longhorn/kbench/tree/main/scripts/build"
    click PackageScripts "https://github.com/longhorn/kbench/tree/main/scripts/package"
    click PackageScripts "https://github.com/longhorn/kbench/tree/main/scripts/validate"
    click PackageScripts "https://github.com/longhorn/kbench/tree/main/scripts/version"
    click BuildImage "https://github.com/longhorn/kbench/tree/main/package/Dockerfile"
    click Entry "https://github.com/longhorn/kbench/tree/main/scripts/entry"
    click RunSh "https://github.com/longhorn/kbench/blob/main/fio/run.sh"
    click CmpRun "https://github.com/longhorn/kbench/blob/main/fio/cmp_run.sh"
    click Parse "https://github.com/longhorn/kbench/blob/main/fio/parse.sh"
    click Parse "https://github.com/longhorn/kbench/blob/main/fio/cmp_parse.sh"
    click Common "https://github.com/longhorn/kbench/blob/main/fio/common-include.fio"
    click BW "https://github.com/longhorn/kbench/blob/main/fio/bw-include.fio"
    click IOPS "https://github.com/longhorn/kbench/blob/main/fio/iops-include.fio"
    click Lat "https://github.com/longhorn/kbench/blob/main/fio/lat-include.fio"
    click JobDefs "https://github.com/longhorn/kbench/tree/main/fio/"
    click Main "https://github.com/longhorn/kbench/blob/main/metric-exporter/main.go"
    click GoMod "https://github.com/longhorn/kbench/blob/main/metric-exporter/go.mod"
    click GoSum "https://github.com/longhorn/kbench/blob/main/metric-exporter/go.sum"
    click MetricsPkg "https://github.com/longhorn/kbench/blob/main/metric-exporter/metrics/metrics.go"
    click RegistryPkg "https://github.com/longhorn/kbench/blob/main/metric-exporter/registry/registry.go"
    click TypesConst "https://github.com/longhorn/kbench/blob/main/metric-exporter/types/constants.go"
    click Types "https://github.com/longhorn/kbench/blob/main/metric-exporter/types/types.go"
    click FioJobPod "https://github.com/longhorn/kbench/blob/main/deploy/fio.yaml"
    click FioJobPod "https://github.com/longhorn/kbench/blob/main/deploy/fio-cmp.yaml"
    click FioJobPod "https://github.com/longhorn/kbench/blob/main/deploy/fio-long-run.yaml"

    %% Styles
    classDef build fill:#FDEBD0,stroke:#E67E22,color:#000
    classDef container fill:#D6EAF8,stroke:#2980B9,color:#000
    classDef k8s fill:#D5F5E3,stroke:#27AE60,color:#000
    classDef external fill:#F2F3F4,stroke:#7F8C8D,color:#000
    classDef file fill:#FCF3CF,stroke:#F1C40F,color:#000
    classDef artifact fill:#EBDEF0,stroke:#9B59B6,color:#000
```
