Skip to main content Skip to complementary content

(Optional) Setting up a Longhorn storage solution for your Kubernetes cluster

Last updated: 8/26/2026

If the preferred shared storage provider for your platform is unavailable, install Longhorn, a distributed block storage system for Kubernetes, in your cluster.

Longhorn is a supported persistent storage option for Dynamic Engine.

Procedure

  1. Verify and install Longhorn prerequisites.
    You can check your cluster according to the specifications in this Longhorn's documentation or use a Longhorn provided environment check script to verify and install missing items.

    A successful environment check can look like this

    [INFO]  Required dependencies 'kubectl jq mktemp sort printf' are installed.
    [INFO]  All nodes have unique hostnames.
    [INFO]  Waiting for longhorn-environment-check pods to become ready (1/2)...
    [INFO]  All longhorn-environment-check pods are ready (2/2).
    [INFO]  MountPropagation is enabled
    [INFO]  Checking kernel release...
    [INFO]  Checking iscsid...
    [INFO]  Checking multipathd...
    [INFO]  Checking packages...
    [ERROR] cryptsetup is not found in ip-10-0-1-51.ec2.internal.
    [ERROR] cryptsetup is not found in ip-10-0-2-58.ec2.internal.
    [INFO]  Checking nfs client...
    [INFO]  Cleaning up longhorn-environment-check pods...
    [INFO]  Cleanup completed.
    You can ignore the cryptsetup is not found error because it is not required by Dynamic Engine.
  2. Install Longhorn with Helm.
    • When installing with Helm, ensure to create a custom values file, for example, longhorn-values.yaml and add the following lines to this file:
      persistence:
        defaultClassReplicaCount: 2 # depends on the number of available nodes in the cluster
        defaultDataLocality: best-effort
        defaultFsType: xfs
        defaultClass: 'true'
      Then at the step of installing Longhorn when following Longhorn's documentation, add -f longhorn-values.yaml to the command to be executed. This makes the whole command reading like:
      helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace --version 1.6.1 -f longhorn-values.yaml
      This command ensures to add a persistence section to the Helm values file used by the Longhorn installation. This way, a persistent storage class is correctly configured.

Results

Verify that the installation is successful by following Longhorn official documentation.

What to do next

If you need to uninstall Longhorn, follow this documentation from Longhorn.

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – please let us know!