Skip to content

Longhorn Storage

Longhorn

Category: Storage Type: Cluster Service Tags: storage · longhorn · dashboard

Overview

Longhorn is a cloud-native distributed block storage system for Kubernetes that provides highly available persistent volumes for your cluster workloads. It offers automatic replication across nodes, scheduled snapshots, backup and restore to S3-compatible storage, and a built-in web dashboard for storage management. Longhorn is designed to be simple to operate and is a popular choice for on-premise and bare-metal Kubernetes clusters that need reliable, replicated storage without a cloud provider.

Version Note: Versions above v1.10.x are not supported due to an upstream CNI compatibility issue with k3s.

How It Works

Cluster Service — Installed once per cluster by an administrator. Once active, Longhorn provides replicated block storage to the whole cluster. Projects can use Longhorn-backed volumes without any per-project setup.

Prerequisites

  • All cluster nodes must have open-iscsi installed and the iscsid service running (required by Longhorn for volume attachment)
  • Sufficient disk capacity on cluster nodes at the configured storage_path
  • A DNS record pointing to your cluster's ingress for the Longhorn dashboard host
  • An nginx ingress controller in the cluster

Installation

  1. Open Terra and navigate to the Plugin Marketplace
  2. Search for "Longhorn Storage"
  3. Click Install
  4. Fill in the configuration fields below
  5. Click Confirm to deploy

Configuration

Install-Time Fields

Field Details
storage_path string · Required · Default: /var/lib/longhorn
Path on host nodes where Longhorn stores volume data
default_replica_count int · Required · Default: 3
Number of replicas for each volume. Higher = more redundancy but more storage used.
fs string · Required · Default: ext4
Default filesystem type for new volumes (ext4, xfs, or btrfs)
release select · Required · Default: v1.10.x
Longhorn version to install
host string · Required
Hostname for the Longhorn management dashboard
prefix string · Optional · Default: /longhorn
URL sub-path for the Longhorn dashboard

Notes

  • The storage_path must exist on all nodes that will store Longhorn volumes — Longhorn will create volume subdirectories within this path
  • A default_replica_count of 3 requires at least 3 nodes; reduce this for single-node or two-node clusters
  • Longhorn creates a longhorn StorageClass that can be used when creating persistent volumes for workloads
  • The Longhorn dashboard provides volume management, snapshot scheduling, and backup configuration
plugins/longhorn/terra.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
resource_id: longhorn
name: Longhorn Storage
icon: https://raw.githubusercontent.com/juno-fx/Terra-Official-Plugins/refs/heads/main/plugins/longhorn/assets/logo.png
description: Longhorn is a cloud-native distributed block storage system for Kubernetes. It provides highly available persistent storage for Kubernetes workloads, with features such as replication, snapshots, and backup/restore capabilities. Longhorn is designed to be easy to use and manage, making it a popular choice for Kubernetes users who need reliable storage solutions.
category: Storage
tags:
  - storage
  - longhorn
  - cluster-level
  - dashboard
fields:
  - name: storage_path
    description: Path where Longhorn will store its data on the host. This should be a path that is not used by any other process and has enough storage capacity to hold your data. Default is `/var/lib/longhorn`.
    required: true
    default: /var/lib/longhorn
  - name: default_replica_count
    description: The default number of replicas for each volume. This determines how many copies of your data will be stored across the cluster. A higher replica count provides better data redundancy and availability, but also consumes more storage space. Default is `3`.
    required: true
    default: 3
    type: int
  - name: fs
    description: The default filesystem type for volumes created by Longhorn. This determines the type of filesystem that will be used when formatting the volumes. Common options include `ext4`, `xfs`, and `btrfs`. Default is `ext4`.
    required: true
    default: ext4
  - name: release
    description: The version of Longhorn to install. Versions above v1.10.x are not supported due to an upstream issue with the Longhorn that can break CNI connections on k3s. https://github.com/longhorn/longhorn/issues/12642
    required: true
    default: v1.10.x
    type: select
    options:
      - v1.10.x
  - name: host
    description: The DNS name of your genesis host.
    required: true
  - name: prefix
    description: Connection URL prefix. i.e. `/longhorn`. Will default to `/longhorn` if not set. This doesn't need changing in most cases.
    required: false