Longhorn installs easily when the cluster is ready for it. The problem is that clusters are often not ready for it.

This note was really about that preparation step.

1. Install the Node Dependencies

Before touching Helm, make sure the nodes have the packages Longhorn expects:

1
2

sudo apt install open-iscsi
sudo apt install jq

Then enable the iSCSI service on the nodes:

1

sudo systemctl enable iscsid

That sounds small, but it is exactly the sort of small missing dependency that wastes time later.

2. Run the Longhorn Environment Check

The most useful command in the note was this one:

1

curl -sSfL https://raw.githubusercontent.com/longhorn/longhorn/v1.5.3/scripts/environment_check.sh | bash

I like this step because it catches the cluster-level assumptions before the actual chart install.

In the original note, the check exposed a few warnings:

  • missing or unreachable routing for the control plane
  • older kernel versions
  • multipathd running on the nodes

That is exactly the kind of feedback you want before you start blaming the storage system itself.

3. Fix the Basic Network Reachability First

One of the quick fixes from the note was simply restoring the expected default route before re-running the check:

1

sudo ip route add default via <gateway-ip>

That is a good reminder that not every “storage install problem” is actually a storage problem.

4. Install Longhorn Only After the Checks Look Reasonable

Once the environment check was clean enough, the chart install was straightforward:

1
2
3
4
5
6
7
8

helm repo add longhorn https://charts.longhorn.io
helm repo update

helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --create-namespace \
  --version 1.5.3 \
  --set persistence.reclaimPolicy="Retain"

Then watch the namespace:

1
2

kubectl get events -n longhorn-system
kubectl get pods -n longhorn-system -w

Closing Thought

The biggest value in this note is not the helm install line. It is the reminder to treat Longhorn as a node-readiness problem first and a chart-install problem second.

That order saves time.