Longhorn 存储 Runbook：安装、查看、调试

Longhorn 是本集群的分布式块存储。它让 Pod 可以申请 PVC，Pod 重启或迁移后数据还在。

1. Longhorn 解决什么问题

没有 Longhorn 时：

Pod 的容器文件系统随 Pod 删除而消失。
数据库、Jenkins、Grafana、Harbor 这类有状态服务不能稳定落盘。
节点坏了，本地盘上的数据很难恢复。

Longhorn 做的事：

提供默认 StorageClass。
PVC 自动创建 Longhorn Volume。
Volume 有多个 replica，分散在不同节点。
CSI 负责把卷 attach/mount 到运行 Pod 的节点。
UI 能查看卷、replica、snapshot、backup。

为什么选 Longhorn：学习和中小集群运维成本低，有 UI，概念比 Ceph 简单。

2. 安装前置

5 台节点都要有：

apt-get update
apt-get install -y open-iscsi nfs-common jq
systemctl enable --now iscsid
modprobe iscsi_tcp
echo iscsi_tcp > /etc/modules-load.d/iscsi_tcp.conf
mkdir -p /var/lib/longhorn

为什么：

Longhorn RWO 块卷通过 iSCSI/engine 暴露给 kubelet。
RWX 卷需要 NFS client。
/var/lib/longhorn 是 Longhorn 数据目录。

确认数据盘不要误格式化：

lsblk -f
df -h

当前环境的 vdb1 已经挂到 /var/lib/containerd，不要 mkfs /dev/vdb。

3. 安装 Longhorn

kubectl create namespace longhorn-system

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.7.2/deploy/longhorn.yaml

小集群要允许 Longhorn 跑在 control-plane 节点：

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

暴露 UI：

kubectl patch svc longhorn-frontend -n longhorn-system \
  -p '{"spec":{"type":"NodePort","ports":[{"port":80,"targetPort":8000,"nodePort":31172}]}}'

设置默认 StorageClass：

kubectl patch storageclass longhorn \
  -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

4. 安装后验收

kubectl get pods -n longhorn-system -o wide
kubectl get sc
kubectl get csidrivers
kubectl get nodes.longhorn.io -n longhorn-system
kubectl get volumes.longhorn.io -n longhorn-system

期望：

longhorn-manager 每节点都有。
longhorn-csi-plugin 每节点都有，且 3/3 Running。
driver.longhorn.io 出现在 kubectl get csidrivers。
longhorn StorageClass 是默认。

5. 创建 PVC 验证

kubectl create ns storage-test

cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
  namespace: storage-test
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: longhorn
---
apiVersion: v1
kind: Pod
metadata:
  name: writer
  namespace: storage-test
spec:
  containers:
  - name: app
    image: busybox:1.36
    command: ["sh", "-c", "date >> /data/hello.txt; sleep 3600"]
    volumeMounts:
    - mountPath: /data
      name: data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: data
EOF

kubectl wait -n storage-test --for=condition=Ready pod/writer --timeout=120s
kubectl exec -n storage-test writer -- cat /data/hello.txt

查 Longhorn 卷：

kubectl get pvc,pv -n storage-test
kubectl get volumes.longhorn.io -n longhorn-system
kubectl get replicas.longhorn.io -n longhorn-system | grep pvc-

6. 看懂状态

kubectl get volumes.longhorn.io -n longhorn-system \
  -o custom-columns=NAME:.metadata.name,STATE:.status.state,ROBUSTNESS:.status.robustness,CURRENT:.status.currentNodeID

字段	含义
`STATE=detached`	卷没挂到任何节点，通常没有 Pod 在用
`STATE=attached`	卷已经挂到某节点
`ROBUSTNESS=healthy`	副本数满足要求
`ROBUSTNESS=degraded`	副本不足或正在重建
`ROBUSTNESS=unknown`	manager/engine 状态不明，需要继续查

看到 degraded 不要马上删卷。先看 replica：

kubectl get replicas.longhorn.io -n longhorn-system \
  -o custom-columns=NAME:.metadata.name,VOLUME:.spec.volumeName,NODE:.spec.nodeID,STATE:.status.currentState,FAILED:.status.failedAt

7. 常见故障

7.1 PVC 一直 Pending

kubectl describe pvc -n <ns> <pvc>
kubectl get sc
kubectl get pods -n longhorn-system
kubectl logs -n longhorn-system deploy/csi-provisioner --tail=100

常见原因：

没有默认 StorageClass。
CSI provisioner 没 Running。
Longhorn manager 不健康。
节点磁盘不可调度。

7.2 Pod 卡在 ContainerCreating / MountVolume

kubectl describe pod -n <ns> <pod>
kubectl get volumeattachments.storage.k8s.io | grep <pvc>
kubectl get volumes.longhorn.io -n longhorn-system | grep <pvc>
journalctl -u kubelet --since "20 min ago" --no-pager | grep -i mount

describe pod 里的 Events 最重要。常见事件：

事件	含义	处理
`driver.longhorn.io not found`	CSI driver 没注册好	查 longhorn-csi-plugin
`Multi-Attach error`	RWO 卷还挂在旧节点	等旧 Pod 删除，必要时查 VolumeAttachment
`volume is not ready for workloads`	Longhorn 卷还在恢复	观察 Longhorn UI / manager 日志
`Input/output error`	卷或 engine I/O 异常	停止自动重试，查 Longhorn engine/replica

7.3 Multi-Attach

RWO 卷同一时间只能挂到一个节点。单副本 Deployment 挂 RWO PVC 时，不要用默认 RollingUpdate，改 Recreate：

kubectl patch deployment -n <ns> <deploy> --type=merge \
  -p '{"spec":{"strategy":{"type":"Recreate","rollingUpdate":null}}}'

如果由 Helm 管理，要把值写回 Helm values，避免下次 upgrade 覆盖。

7.4 degraded 卷

VOL=pvc-xxxx

kubectl get volumes.longhorn.io -n longhorn-system $VOL -o yaml | sed -n '1,220p'
kubectl get replicas.longhorn.io -n longhorn-system -l longhornvolume=$VOL -o wide
kubectl get engines.longhorn.io -n longhorn-system -l longhornvolume=$VOL -o yaml | grep -A20 replicaModeMap

原则：

业务还在 Running 时，先观察 replica rebuild，不要删 PVC。
WO 通常表示副本正在写入/重建。
RW 表示 engine 正在读写这个 replica。
多个副本都失败时，先做快照/备份评估，再操作。

8. UI 入口

http://154.201.73.31:31172

UI 里重点看：

Node：节点是否 schedulable、磁盘剩余。
Volume：state、robustness、attached node。
Replica：分布在哪些节点，是否 rebuilding。
Event log：Longhorn 自身错误。