Operations¶

Scope

Kubernetes distributed storage operations including volume management, backup/DR, performance tuning, and node maintenance.

Deployment¶

# Helm install (recommended)
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system --create-namespace \
  --set defaultSettings.defaultReplicaCount=3 \
  --set defaultSettings.storageOverProvisioningPercentage=200

Volume Operations¶

# Check volume health
kubectl -n longhorn-system get volumes.longhorn.io

# Force detach stuck volume
kubectl -n longhorn-system patch volumes.longhorn.io <vol> \
  --type=merge -p '{"spec":{"nodeID":""}}'

StorageClass Configuration¶

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: longhorn-fast
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "3"
  dataLocality: "best-effort"
  diskSelector: "ssd"
reclaimPolicy: Delete
volumeBindingMode: Immediate

Backup & DR¶

# Create backup target (S3-compatible)
# Settings > Backup Target: s3://longhorn-backup@us-east-1/
# Settings > Backup Target Credential Secret: aws-secret

# Recurring backup schedule
kubectl apply -f - <<EOF
apiVersion: longhorn.io/v1beta2
kind: RecurringJob
metadata:
  name: daily-backup
  namespace: longhorn-system
spec:
  cron: "0 2 * * *"
  task: backup
  retain: 7
  concurrency: 2
EOF

Performance Tuning¶

Setting	Default	Recommended	Impact
Replica count	3	3 (HA) / 2 (perf)	Storage overhead vs durability
Data locality	disabled	best-effort	Reduces cross-node I/O
Replica soft anti-affinity	true	true	Spread replicas across nodes
Guaranteed engine manager CPU	12	25	Reduces I/O scheduling latency

Common Issues¶

Issue	Diagnosis	Fix
Volume degraded	UI > Volume details	Check node/disk health
Rebuild slow	`longhornctl check`	Increase replica rebuild threads
PVC stuck Pending	`kubectl describe pvc`	Check StorageClass, node labels
Disk pressure	`kubectl top nodes`	Add disks, delete unused volumes

Commands & Recipes¶

Installation¶

# Install via Helm
helm repo add longhorn https://charts.longhorn.io
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --create-namespace \
  --set defaultSettings.defaultReplicaCount=3

# Access UI
kubectl port-forward -n longhorn-system svc/longhorn-frontend 8080:80

Volume Management¶

# StorageClass
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-fast
provisioner: driver.longhorn.io
allowVolumeExpansion: true
parameters:
  numberOfReplicas: "3"
  staleReplicaTimeout: "2880"
  fsType: ext4

# PVC
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mydata
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn-fast
  resources:
    requests:
      storage: 10Gi

Backup & Restore¶

# Configure backup target (S3)
kubectl -n longhorn-system edit settings backup-target
# Set to: s3://my-backup-bucket@us-east-1/

# Create backup via kubectl
kubectl -n longhorn-system create -f - <<EOF
apiVersion: longhorn.io/v1beta2
kind: Backup
metadata:
  name: mydata-backup
spec:
  snapshotName: mydata-snap-1
EOF

Troubleshooting¶

# Check volume status
kubectl -n longhorn-system get volumes.longhorn.io
kubectl -n longhorn-system get replicas.longhorn.io

# Check engine status
kubectl -n longhorn-system get engines.longhorn.io

# View Longhorn manager logs
kubectl -n longhorn-system logs -l app=longhorn-manager -f

# Node health
kubectl -n longhorn-system get nodes.longhorn.io -o wide

Sources¶

Longhorn CLI / kubectl