# longhorn/longhorn architecture

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

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

## Overview

##### Project Type and Purpose
- Longhorn is a cloud-native, distributed block storage system for Kubernetes.
- Its purpose is to provide persistent volume support by replicating block storage across multiple nodes and enabling features such as snapshots, backups, and automated upgrades.
- The README explains that multiple microservices (e.g., Manager, Instance Manager, Engine, Share Manager, Backing Image Manager) work together to manage storage volumes in a Kubernetes cluster.

##### File Structure for Architectural Clues
- Top-level Directories:
- .github: Contains workflow definitions, issue/PR templates, and continuous integration configuration indicating the rigorous development process and automated testing.
- chart & deploy: Provide Helm charts and Kubernetes manifests for deployment; this indicates strong integration with the Kubernetes ecosystem.
- dev, examples, and scalability: These directories offer deployment examples, scripts, and scalability guidelines which emphasize how the system is configured and scaled.
- enhancements: Contains documents that chronicle the evolution of features and improvements, hinting at a modular design where components can evolve independently.

##### Key Components and Their Relationships
- Core Components (as per the README and file tree):
- Longhorn Manager: Acts as the primary orchestrator by managing distributed storage and exposing a CSI driver for Kubernetes.
- Instance Manager: Manages the lifecycle of controller/replica instances and ensures the high availability of storage volumes.
- Longhorn Engine: Responsible for the core logic around volume control, replication, and volume operations.
- Longhorn Share Manager: Provides NFS export functionality so that volumes can be exposed as ReadWriteMany (RWX).
- Backing Image Manager: Handles the downloading, syncing, and deletion of disk images that back the volume replicas.
- Longhorn UI: Offers a dashboard for administrators to manage volumes, monitor system health, and perform operations.
- Supporting Libraries/Helpers:
- Libraries for iSCSI and SPDK operations hint at specialized protocols and performance optimizations.
- Backup Store and other common libraries indicate integration with external storage systems for backup and recovery.

##### Relationships and Interactions
- How the Longhorn Manager interacts with the Kubernetes API to schedule and orchestrate the various microservices.
- Interactions among Manager, Instance Manager, and Engine – for example:
- The Manager controls high-level orchestration and triggers volume provisioning.
- The Instance Manager creates and manages container instances that run the storage controllers and replicas.
- The Engine is embedded in those containers to handle the replication logic and I/O processing.
- Backing Image Manager’s role in ensuring that disk images are available and synced across nodes.
- How external backup processes (using the backup store and change block detection) integrate with these components.

##### Additional Architectural Patterns to Highlight
- Distributed and fault-tolerant design: Demonstrate synchronous replica creation and node distribution.
- Microservices architecture: Clearly show how each component is a standalone service managed by container orchestration.
- Integration with standard Kubernetes patterns (e.g., use of Helm charts for deployment, CRDs for volume definitions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster Environment
    subgraph "Kubernetes Cluster Environment"
        KAPI["Kubernetes API"]:::k8s
        Nodes["Cluster Nodes"]:::k8s
    end

    %% Storage Service Layer
    subgraph "Storage Service Layer"
        LM["Longhorn Manager"]:::control
        IM["Instance Manager"]:::control
        LE["Longhorn Engine"]:::storage
        BM["Backing Image Manager"]:::storage
        SM["Longhorn Share Manager"]:::storage
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Longhorn UI"]:::ui
    end

    %% External Integrations
    subgraph "External Integrations"
        BS["Backup Store"]:::external
    end

    %% Relationships
    KAPI -->|"orchestrates"| LM
    LM -->|"controls"| IM
    IM -->|"triggers"| LE
    LE -->|"syncsImagesTo"| BM
    LM -->|"schedulesShare"| SM
    LM -->|"exposesDashboard"| UI
    BM -->|"backsUpTo"| BS

    %% Click Events
    click LM "https://github.com/longhorn/longhorn/blob/master/chart/templates/deployment-driver.yaml"
    click LM "https://github.com/longhorn/longhorn/blob/master/chart/templates/manager-network-policy.yaml"
    click IM "https://github.com/longhorn/longhorn/blob/master/chart/templates/network-policies/instance-manager-networking.yaml"
    click LE "https://github.com/longhorn/longhorn/blob/master/deploy/longhorn.yaml"
    click SM "https://github.com/longhorn/longhorn/blob/master/enhancements/20240402-share-manager-scheduling.md"
    click BM "https://github.com/longhorn/longhorn/blob/master/chart/templates/network-policies/backing-image-manager-network-policy.yaml"
    click UI "https://github.com/longhorn/longhorn/blob/master/chart/templates/deployment-ui.yaml"

    %% Styles
    classDef k8s fill:#aqua,stroke:#333,stroke-width:2px;
    classDef control fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef storage fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef ui fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#f2f2f2,stroke:#333,stroke-dasharray: 3 3,stroke-width:2px;
```
