# Longhorn Cloud-Native Storage

> Lightweight distributed block storage for Kubernetes with snapshots and backups.

- Category: Storage & Backup
- Difficulty: advanced
- Components: longhorn-manager, longhorn-ui, longhorn-engine, minio
- Tags: longhorn, block-storage, kubernetes, snapshots, backups
- Source: https://docker.recipes/storage/longhorn-storage

## Overview

Longhorn is a cloud-native distributed block storage system designed specifically for Kubernetes environments, originally developed by Rancher Labs and now part of the CNCF landscape. The longhorn-manager serves as the orchestration engine that coordinates storage operations, handles volume lifecycle management, and maintains cluster-wide storage metadata across distributed nodes. This lightweight yet powerful storage solution addresses the critical challenge of providing persistent, replicated storage for containerized applications without requiring expensive SAN infrastructure or vendor lock-in.

This configuration combines Longhorn's core components with MinIO to create a comprehensive storage ecosystem for containerized environments. The longhorn-manager orchestrates storage operations while longhorn-engine handles the actual block device operations and data replication across nodes. The longhorn-ui provides a web interface for managing volumes, snapshots, and backups, while MinIO serves as the S3-compatible backend for storing Longhorn backups and snapshots outside the cluster.

This stack is ideal for platform engineers, DevOps teams, and organizations building Kubernetes infrastructure who need enterprise-grade storage features like snapshots, cross-cluster replication, and disaster recovery without the complexity of traditional SAN solutions. The combination provides both local high-performance block storage and remote backup capabilities, making it particularly valuable for stateful applications requiring data durability guarantees.

## Features

- Distributed block storage with configurable replica counts across multiple nodes for high availability
- Incremental snapshot functionality with space-efficient storage and instant recovery capabilities
- Cross-cluster backup and restore using S3-compatible storage backends like the integrated MinIO
- Volume expansion and migration without downtime for running applications
- Built-in data locality optimization to reduce network overhead during read operations
- Disaster recovery with scheduled backup policies and cross-region replication support
- Real-time volume health monitoring with automatic replica rebuilding on node failures
- CSI driver integration providing native Kubernetes StorageClass and PVC support

## Use cases

- Kubernetes clusters requiring persistent storage for databases like PostgreSQL, MySQL, or MongoDB
- CI/CD environments needing reliable storage for build artifacts and test data with snapshot rollback capabilities
- Multi-tenant SaaS platforms requiring isolated storage with backup and disaster recovery per tenant
- Edge computing deployments where traditional SAN storage is impractical but data persistence is critical
- Development and staging environments needing production-like storage with easy snapshot-based environment cloning
- Hybrid cloud setups requiring consistent storage behavior between on-premises and cloud Kubernetes clusters
- Backup consolidation for multiple applications using MinIO as a centralized S3-compatible storage backend

## Prerequisites

- Minimum 4GB RAM available with at least 2GB allocated to longhorn-manager for metadata operations
- Docker host with privileged container support and access to /dev for block device operations
- Ports 8000, 9000, 9001, and 9500 available for Longhorn UI, MinIO API, MinIO console, and manager API respectively
- Understanding of block storage concepts, CSI drivers, and Kubernetes storage primitives
- Basic knowledge of S3 API operations for configuring backup destinations and retention policies
- Sufficient disk space with separate volumes recommended for Longhorn data and MinIO storage backends

## docker-compose.yml

```yaml
services:
  longhorn-manager:
    image: longhornio/longhorn-manager:latest
    privileged: true
    ports:
      - "9500:9500"
    environment:
      - LONGHORN_MANAGER_IP=longhorn-manager
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - longhorn_data:/var/lib/longhorn
      - /dev:/dev
    networks:
      - longhorn-net
    restart: unless-stopped

  longhorn-ui:
    image: longhornio/longhorn-ui:latest
    ports:
      - "8000:8000"
    environment:
      - LONGHORN_MANAGER_IP=http://longhorn-manager:9500
    depends_on:
      - longhorn-manager
    networks:
      - longhorn-net
    restart: unless-stopped

  longhorn-engine:
    image: longhornio/longhorn-engine:latest
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - longhorn_engine:/engine
    networks:
      - longhorn-net
    restart: unless-stopped

  minio:
    image: minio/minio:latest
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    networks:
      - longhorn-net
    restart: unless-stopped

volumes:
  longhorn_data:
  longhorn_engine:
  minio_data:

networks:
  longhorn-net:
    driver: bridge
```

## .env

```bash
# MinIO Backup Target
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=secure_minio_password

# Longhorn Settings
LONGHORN_DEFAULT_DATA_PATH=/var/lib/longhorn
```

## Usage notes

- Longhorn UI at http://localhost:8000
- Manager API at http://localhost:9500
- MinIO console at http://localhost:9001
- Best used with Kubernetes, standalone mode limited

## Troubleshooting

- longhorn-manager fails with 'permission denied' accessing /dev: Ensure the container runs in privileged mode and the Docker daemon has access to block devices
- Longhorn UI shows 'Manager API unreachable': Verify longhorn-manager container is running and port 9500 is accessible within the Docker network
- Volume attachment fails with 'no healthy replicas': Check that longhorn-engine containers are running and have sufficient disk space in mounted volumes
- MinIO backup configuration fails with 'AccessDenied': Verify MINIO_ACCESS_KEY and MINIO_SECRET_KEY environment variables are properly set and match Longhorn backup target credentials
- Snapshot creation fails with 'insufficient space': Monitor the longhorn_data volume usage and ensure adequate free space for snapshot metadata and differentials
- Engine process crashes with 'device busy': Stop any processes accessing Longhorn volumes and ensure proper volume unmounting before container restarts

