Документация по установке и использованию Longhorn в кластере.

Оглавление

• Описание
• Быстрый старт
• Архитектура
• Команды
• Storage Classes
• Примеры использования
• Troubleshooting
• Ссылки

Описание

Longhorn - cloud-native distributed block storage для Kubernetes от Rancher.

Почему Longhorn?

• ✅ Совместимость с x86-64-v1 - работает на старых CPU без SSE4.2/AVX
• ✅ Простая установка - Helm chart, минимальная конфигурация
• ✅ Легковесность - меньше ресурсов чем Ceph
• ✅ Быстрая репликация - оптимизирована для Kubernetes
• ✅ Удобный UI - понятный веб-интерфейс
• ✅ Snapshot и backup - встроенная поддержка
• ✅ Production-ready - используется в production кластерах

Текущая конфигурация

• Namespace: longhorn-system
• Worker ноды: 3 (по 100 GB на каждой)
• Реплики: 3 по умолчанию
• Total usable storage: ~70 GB
• iSCSI: для подключения volumes между нодами

Naming Convention

Все namespace следуют префиксной структуре с дефисом (RFC 1123):

• tech-* - Техническая инфраструктура (storage, monitoring, logging)
• prod-* - Production окружение приложений
• dev-* - Development окружение (опционально)
• stage-* - Staging окружение (опционально)

Примеры:

• longhorn-system - Rook-Ceph storage
• tech-monitoring - Prometheus, Grafana
• tech-logging - ELK/Loki stack
• prod-api-gateway - Production API Gateway
• prod-backend - Production backend services

Примечание: Kubernetes требует DNS-совместимые имена (lowercase + дефис), поэтому используем - вместо _.

Быстрый старт

1. Подготовка worker нод (один раз)

Установка зависимостей через Ansible:

1
2

cd ../../infra
make longhorn-prepare-nodes

Это установит на worker нодах: - open-iscsi - для iSCSI подключений volumes между нодами - nfs-common - для NFS поддержки - util-linux - системные утилиты

Почему iscsid? Longhorn использует iSCSI протокол для подключения volumes с одной ноды к подам на других нодах. Без iscsid volumes будут доступны только локально.

2. Установка Longhorn

1
2

cd k8s
make longhorn-install-all

Эта команда: 1. Проверит наличие зависимостей 2. Создаст namespace longhorn-system 3. Установит Longhorn через Helm 4. Создаст Storage Classes 5. Дождется готовности всех компонентов

3. Проверка статуса

1

make longhorn-status

Показывает: - Статус Manager, UI, CSI drivers - Список нод и их готовность - Доступные Storage Classes

4. Доступ к UI

1

make longhorn-dashboard

Откроется на http://localhost:8080

UI показывает: - 📊 Состояние нод и дисков - 💾 Список volumes и их реплики - ⚙️ Настройки и конфигурацию - 📈 Статистику использования

Команды

Все команды запускаются из директории infra/k8s/:

Управление

1
2
3
4
5

make longhorn-install-all    # Полная установка с проверками
make longhorn-install        # Только установка (без проверок)
make longhorn-status         # Показать статус компонентов
make longhorn-dashboard      # Открыть UI (port-forward)
make longhorn-uninstall      # Удалить Longhorn (УДАЛЯЕТ ДАННЫЕ!)

Справка

1
2

make help               # Общая справка
make longhorn-help      # Справка по Longhorn

Storage Classes

После установки доступны два storage class:

1. longhorn - Default

• Distributed block storage
• Для баз данных, stateful приложений
• ReadWriteOnce (RWO)
• Поддержка resize и snapshot
• ReclaimPolicy: Delete (автоудаление при удалении PVC)
• 3 реплики по умолчанию

Пример PVC:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-data
spec:
  storageClassName: longhorn
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

2. longhorn-retain

• То же что и longhorn, но с ReclaimPolicy: Retain
• Данные сохраняются после удаления PVC
• Для критичных данных (backups, важные БД)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: vault-data
spec:
  storageClassName: longhorn-retain
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi

Ограничения

⚠️ Longhorn поддерживает только RWO (ReadWriteOnce)

Для ReadWriteMany (RWX) используйте: - NFS Server поверх Longhorn volume - Отдельное решение (NFS-Ganesha, CephFS)

Примеры использования

PostgreSQL StatefulSet

 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

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-data
  namespace: tech-postgres
spec:
  storageClassName: longhorn-retain  # Retain для БД!
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
  namespace: tech-postgres
spec:
  serviceName: postgres
  replicas: 1
  template:
    spec:
      containers:
      - name: postgres
        image: postgres:17
        volumeMounts:
        - name: data
          mountPath: /var/lib/postgresql/data
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: postgres-data

Проверка volume

1
2
3
4
5
6
7
8

# Список всех volumes
kubectl -n longhorn-system get volumes.longhorn.io

# Детали конкретного volume
kubectl -n longhorn-system describe volume/pvc-xxx

# Статус реплик
kubectl -n longhorn-system get replicas.longhorn.io

Архитектура

Компоненты

Storage Backend

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

Worker Node 1: /var/lib/longhorn  (70 GB)
     ├── Volume A replica 1
     ├── Volume B replica 2
     └── Volume C replica 3

Worker Node 2: /var/lib/longhorn  (70 GB)
     ├── Volume A replica 2
     ├── Volume B replica 3
     └── Volume C replica 1

Worker Node 3: /var/lib/longhorn  (70 GB)
     ├── Volume A replica 3
     ├── Volume B replica 1
     └── Volume C replica 2

• Тип: Распределенное блочное хранилище
• Расположение: /var/lib/longhorn на worker нодах
• Реплики: 3 копии по умолчанию
• Snapshots: Инкрементальные снимки
• Подключение: iSCSI протокол

Отказоустойчивость

• ✅ Host-level anti-affinity - реплики на разных нодах
• ✅ Автовосстановление - при падении ноды
• ✅ Быстрая репликация - синхронизация < 1 минуты
• ✅ Backup на S3/NFS - для disaster recovery
• ⚠️ Минимум 2 ноды для работы (из 3 при 3 репликах)

Требования

Cluster:

• Kubernetes 1.28+
• Минимум 3 worker ноды
• Доступ к kubeconfig

Worker Nodes:

• ОС: Linux
• Минимум 4GB RAM на ноду
• Минимум 20GB свободного места в /var/lib/longhorn
• Пакеты: open-iscsi, nfs-common (устанавливаются автоматически)

Инструменты:

• kubectl
• helm
• make

Удаление

⚠️ ВНИМАНИЕ: Это удалит ВСЕ данные в Longhorn!

1
2

# Удалить Longhorn с подтверждением (10 сек)
make uninstall-longhorn

Longhorn автоматически очистит данные с нод при удалении.

Мониторинг

После установки доступны: - Longhorn UI (http://localhost:8080 через port-forward) - Prometheus metrics endpoint - Grafana dashboards (можно импортировать официальные)

Следующие шаги

После установки storage можно настраивать: - ✅ Storage layer (Longhorn) - установлен - ⬜ Secrets management (Vault) - использует Longhorn - ⬜ Databases (PostgreSQL) - использует Longhorn - ⬜ Object Storage (MinIO/S3) - использует Longhorn - ⬜ Monitoring (Prometheus/Grafana) - ⬜ Logging (ELK/Loki)

Troubleshooting

Longhorn pods не стартуют

1
2
3
4
5

# Проверить логи manager
kubectl -n longhorn-system logs -l app=longhorn-manager

# Проверить статус нод
kubectl -n longhorn-system get nodes.longhorn.io

Зависимости не установлены

Longhorn требует open-iscsi на worker нодах:

1
2
3
4
5
6
7

# Установить через Ansible
cd ../../infra
make longhorn-prepare-nodes

# Проверить вручную на ноде
ssh worker1
systemctl status iscsid

Что делает iscsid? - Управляет iSCSI подключениями - Позволяет монтировать volumes с других нод - Необходим для distributed storage

Volume не создается

1
2
3
4
5
6

# Проверить CSI provisioner
kubectl -n longhorn-system get pods -l app=csi-provisioner
kubectl -n longhorn-system logs -l app=csi-provisioner

# Проверить доступное место на нодах
kubectl -n longhorn-system get nodes.longhorn.io -o wide

Replica не синхронизируется

1
2
3
4
5
6
7

# Проверить в Longhorn UI:
# - Volume → Detail → показывает статус реплик
# - Node → Detail → показывает диски и их использование

# Или через kubectl:
kubectl -n longhorn-system get volumes.longhorn.io
kubectl -n longhorn-system describe volume/<volume-name>

Включить работу Longhorn на control-plane нодах в рантайме

Если кластер уже развёрнут и Longhorn установлен только на worker-ноды, можно включить поддержку control-plane без переустановки:

1. Разрешить Longhorn игнорировать taint control-plane:

1
2

kubectl -n longhorn-system patch settings.longhorn.io taint-toleration \
  --type=merge -p '{"value":"node-role.kubernetes.io/control-plane:NoSchedule"}'

1. Добавить toleration для CSI плагина, чтобы он поставился на все ноды:

1
2
3

kubectl -n longhorn-system patch ds longhorn-csi-plugin \
  --type='json' \
  -p='[{"op":"add","path":"/spec/template/spec/tolerations","value":[{"key":"node-role.kubernetes.io/control-plane","operator":"Exists","effect":"NoSchedule"}]}]'

1. Добавить toleration для engine image DaemonSet (движок Longhorn на каждой ноде):

Сначала найти имя DaemonSet'а:

1

kubectl -n longhorn-system get ds | grep engine-image

Затем пропатчить его (подставь своё имя вместо engine-image-ei-XXXX):

1
2
3

kubectl -n longhorn-system patch ds engine-image-ei-XXXX \
  --type='json' \
  -p='[{"op":"add","path":"/spec/template/spec/tolerations","value":[{"key":"node-role.kubernetes.io/control-plane","operator":"Exists","effect":"NoSchedule"}]}]'

1. Проверить, что компоненты стоят на всех нодах:

1
2
3

kubectl -n longhorn-system get pods -l app=longhorn-csi-plugin -o wide
kubectl -n longhorn-system get pods -l longhorn.io/component=engine-image -o wide
kubectl get csinode -o wide

Для новых установок все эти настройки уже зашиты в charts/longhorn/values.yaml, поэтому достаточно обычного make longhorn-install-all.

Manager pods падают на control-plane

Это нормально если зависимости установлены только на workers:

1
2
3
4

# Проверить где падают
kubectl -n longhorn-system get pods -l app=longhorn-manager -o wide

# Должны быть Running на workers, CrashLoop на masters

Longhorn manager запускается на всех нодах, но storage используется только на workers.

Ссылки

• 📚 Longhorn Documentation
• 🔧 Longhorn Best Practices
• ☸️ Kubernetes Storage
• 🎓 Longhorn Architecture

← Назад к главной документации