Longhorn Cloud-Native Storage

advanced

Lightweight distributed block storage for Kubernetes with snapshots and backups.

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.

Key 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

Common Use Cases

1Kubernetes clusters requiring persistent storage for databases like PostgreSQL, MySQL, or MongoDB
2CI/CD environments needing reliable storage for build artifacts and test data with snapshot rollback capabilities
3Multi-tenant SaaS platforms requiring isolated storage with backup and disaster recovery per tenant
4Edge computing deployments where traditional SAN storage is impractical but data persistence is critical
5Development and staging environments needing production-like storage with easy snapshot-based environment cloning
6Hybrid cloud setups requiring consistent storage behavior between on-premises and cloud Kubernetes clusters
7Backup 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  longhorn-manager: 
3    image: longhornio/longhorn-manager:latest
4    privileged: true
5    ports: 
6      - "9500:9500"
7    environment: 
8      - LONGHORN_MANAGER_IP=longhorn-manager
9    volumes: 
10      - /var/run/docker.sock:/var/run/docker.sock
11      - longhorn_data:/var/lib/longhorn
12      - /dev:/dev
13    networks: 
14      - longhorn-net
15    restart: unless-stopped
16
17  longhorn-ui: 
18    image: longhornio/longhorn-ui:latest
19    ports: 
20      - "8000:8000"
21    environment: 
22      - LONGHORN_MANAGER_IP=http://longhorn-manager:9500
23    depends_on: 
24      - longhorn-manager
25    networks: 
26      - longhorn-net
27    restart: unless-stopped
28
29  longhorn-engine: 
30    image: longhornio/longhorn-engine:latest
31    privileged: true
32    volumes: 
33      - /var/run/docker.sock:/var/run/docker.sock
34      - longhorn_engine:/engine
35    networks: 
36      - longhorn-net
37    restart: unless-stopped
38
39  minio: 
40    image: minio/minio:latest
41    ports: 
42      - "9000:9000"
43      - "9001:9001"
44    environment: 
45      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
46      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
47    volumes: 
48      - minio_data:/data
49    command: server /data --console-address ":9001"
50    networks: 
51      - longhorn-net
52    restart: unless-stopped
53
54volumes: 
55  longhorn_data: 
56  longhorn_engine: 
57  minio_data: 
58
59networks: 
60  longhorn-net: 
61    driver: bridge

.env Template

.env

1# MinIO Backup Target
2MINIO_ACCESS_KEY=minioadmin
3MINIO_SECRET_KEY=secure_minio_password
4
5# Longhorn Settings
6LONGHORN_DEFAULT_DATA_PATH=/var/lib/longhorn

Usage Notes

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

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

longhorn-manager

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

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

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  longhorn-manager:
5    image: longhornio/longhorn-manager:latest
6    privileged: true
7    ports:
8      - "9500:9500"
9    environment:
10      - LONGHORN_MANAGER_IP=longhorn-manager
11    volumes:
12      - /var/run/docker.sock:/var/run/docker.sock
13      - longhorn_data:/var/lib/longhorn
14      - /dev:/dev
15    networks:
16      - longhorn-net
17    restart: unless-stopped
18
19  longhorn-ui:
20    image: longhornio/longhorn-ui:latest
21    ports:
22      - "8000:8000"
23    environment:
24      - LONGHORN_MANAGER_IP=http://longhorn-manager:9500
25    depends_on:
26      - longhorn-manager
27    networks:
28      - longhorn-net
29    restart: unless-stopped
30
31  longhorn-engine:
32    image: longhornio/longhorn-engine:latest
33    privileged: true
34    volumes:
35      - /var/run/docker.sock:/var/run/docker.sock
36      - longhorn_engine:/engine
37    networks:
38      - longhorn-net
39    restart: unless-stopped
40
41  minio:
42    image: minio/minio:latest
43    ports:
44      - "9000:9000"
45      - "9001:9001"
46    environment:
47      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
48      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
49    volumes:
50      - minio_data:/data
51    command: server /data --console-address ":9001"
52    networks:
53      - longhorn-net
54    restart: unless-stopped
55
56volumes:
57  longhorn_data:
58  longhorn_engine:
59  minio_data:
60
61networks:
62  longhorn-net:
63    driver: bridge
64EOF
65
66# 2. Create the .env file
67cat > .env << 'EOF'
68# MinIO Backup Target
69MINIO_ACCESS_KEY=minioadmin
70MINIO_SECRET_KEY=secure_minio_password
71
72# Longhorn Settings
73LONGHORN_DEFAULT_DATA_PATH=/var/lib/longhorn
74EOF
75
76# 3. Start the services
77docker compose up -d
78
79# 4. View logs
80docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/longhorn-storage/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

longhorn-managerlonghorn-uilonghorn-engineminio

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download