跳到主要内容

K3s Longhorn 安装指南

0. Longhorn 简介​

Longhorn 是一款轻量级、可靠且易用的 Kubernetes 分布式块存储解决方案，由 Rancher 开发并捐赠给 CNCF。它专为云原生环境设计，提供了丰富的存储功能和良好的用户体验。

0.1 Longhorn 优势​

  • 轻量级设计：资源占用少，适合各种规模的 Kubernetes 集群
  • 易于部署和管理：提供直观的 Web UI，简化存储管理
  • 高可用性：支持多副本存储（默认 3 副本），确保数据安全
  • 丰富的功能集：支持快照、备份、恢复、卷克隆等高级功能
  • 良好的扩展性：支持动态扩展存储容量
  • 与 Kubernetes 深度集成：原生支持 Kubernetes API
  • 开源免费：基于 Apache 2.0 许可证

0.2 适用场景​

  • K3s 集群持久化存储：为 K3s 集群提供可靠的持久化存储
  • 中小规模生产环境：适合 100 节点以内的集群
  • 边缘计算：轻量级设计适合边缘设备
  • DevOps 环境：快速部署和管理，适合开发测试场景
  • 混合云环境：支持跨云存储管理

1. 系统要求​

1.1 节点要求​

  • 节点数量：至少 3 个节点（推荐），支持单节点测试
  • Kubernetes 版本：K3s v1.20+（Longhorn v1.4+ 支持）
  • 操作系统：Linux 发行版（Ubuntu、CentOS、Debian 等）

1.2 硬件要求​

  • CPU：每个节点至少 2 CPU 核心
  • 内存：每个节点至少 4 GB RAM
  • 磁盘：
    • 至少 10 GB 可用空间用于 Longhorn 组件
    • 推荐使用 SSD 以获得更好的性能
    • 每个节点至少有一个未格式化的磁盘或分区（可选，用于 Longhorn 存储）

1.3 网络要求​

  • 节点间网络连通性良好
  • 推荐使用 1 Gbps 或更快的网络
  • 确保以下端口可用：
    • 2049：NFS（用于备份）
    • 30000-32767：Longhorn 节点端口范围（用于内部组件通信）

2. 安装前准备​

2.1 前置条件说明​

  • MetalLB：已默认安装并配置完成，用于提供 LoadBalancer 服务的外部 IP 地址
  • 固定 IP：将为 Longhorn UI 分配固定 IP 地址，确保服务可稳定访问

2.2 安装 open-iscsi​

Longhorn 需要在所有节点上安装 open-iscsi 或 iscsiadm 来管理块存储。

2.2.1 Ubuntu/Debian 系统​

sudo apt update
sudo apt install -y open-iscsi
sudo systemctl enable --now iscsid

2.2.2 CentOS/RHEL 系统​

sudo yum install -y iscsi-initiator-utils
sudo systemctl enable --now iscsid

2.3 可选：指定特定硬盘（安装前配置）​

如果你想让 Longhorn 使用特定的硬盘，可以在安装前通过节点标签来指定。

# 替换 <node-name> 为节点名称
# 替换 /dev/sdb 和 /dev/sdc 为你想要使用的磁盘
kubectl label nodes <node-name> node.longhorn.io/default-disks-config='[{"path":"/dev/sdb","allowScheduling":true},{"path":"/dev/sdc","allowScheduling":true}]'

# 可选：为节点添加标签，控制是否创建默认磁盘
kubectl label nodes <node-name> node.longhorn.io/create-default-disk=true

3. 快速部署 Longhorn（推荐）​

3.1 方法一：使用 Helm 部署（带固定 IP）​

这是推荐的部署方式，简单快捷，支持固定 IP 配置。

3.1.1 安装 Helm（如果尚未安装）​

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
sudo chmod 700 get_helm.sh
sudo ./get_helm.sh

3.1.2 添加 Longhorn Helm 仓库​

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

3.1.3 部署 Longhorn（带固定 IP）​

# 替换 10.2.10.150 为你想要的固定 IP 地址
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --create-namespace \
  --version 1.5.3 \
  --set ui.service.type=LoadBalancer \
  --set ui.service.loadBalancerIP=10.2.10.150

3.2 方法二：使用 YAML 文件部署​

这是另一种部署方式，适合没有 Helm 的环境。

3.2.1 基本部署​

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

3.2.2 配置固定 IP（部署后）​

# 替换 10.2.10.150 为你想要的固定 IP 地址
kubectl patch svc longhorn-frontend -n longhorn-system \
  -p '{"spec":{"type":"LoadBalancer","loadBalancerIP":"10.2.10.150"}}'

4. 部署验证​

4.1 检查 Longhorn Pod 状态​

kubectl -n longhorn-system get pods

所有 Pod 应处于 Running 状态。

4.2 访问 Longhorn Web UI​

使用浏览器访问你配置的固定 IP（例如：http://10.2.10.150），可以看到 Longhorn Web UI 界面。

4.3 检查 Longhorn 存储类​

kubectl get storageclass

应该看到默认的 longhorn 存储类。

5. 简单使用示例​

5.1 创建 PVC​

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

保存为 pvc.yaml，然后执行：

kubectl apply -f pvc.yaml

5.2 在 Pod 中使用 PVC​

apiVersion: v1
kind: Pod
metadata:
  name: nginx-with-longhorn
spec:
  containers:
  - name: nginx
    image: nginx:latest
    ports:
    - containerPort: 80
    volumeMounts:
    - name: nginx-storage
      mountPath: /usr/share/nginx/html
  volumes:
  - name: nginx-storage
    persistentVolumeClaim:
      claimName: longhorn-pvc

保存为 pod.yaml，然后执行：

kubectl apply -f pod.yaml

5.3 验证 PVC 和 Pod​

# 检查 PVC 状态
kubectl get pvc longhorn-pvc

# 检查 Pod 状态
kubectl get pod nginx-with-longhorn

6. 基本管理操作​

6.1 登录 Longhorn UI​

使用浏览器访问你配置的固定 IP（例如：http://10.2.10.150）。

6.2 查看卷信息​

  1. 登录 Longhorn UI
  2. 导航到 "Volumes" 页面
  3. 查看所有卷的状态和信息

6.3 创建快照​

  1. 在 "Volumes" 页面找到要创建快照的卷
  2. 点击 "Take Snapshot" 按钮
  3. 输入快照名称，点击 "OK"

6.4 创建备份​

  1. 确保已配置备份目标（在 "Settings" -> "General" 中）
  2. 在 "Volumes" 页面找到要备份的卷
  3. 点击 "Backup" 按钮
  4. 输入备份名称，点击 "OK"

7. 安装后配置（可选）​

7.1 安装后添加特定硬盘​

如果你在安装前没有指定特定硬盘，可以在安装后通过 Web UI 手动添加。

  1. 登录 Longhorn UI
  2. 导航到 "Nodes" 页面
  3. 点击要配置的节点
  4. 点击 "Add Disk" 按钮
  5. 选择磁盘路径和配置选项
  6. 点击 "Save" 按钮

7.2 使用 values.yaml 自定义配置​

对于更复杂的配置，可以使用 values.yaml 文件重新部署或升级 Longhorn。

7.2.1 创建 values.yaml 文件​

defaultSettings:
  # 存储配置
  defaultReplicaCount: 3  # 默认副本数
  defaultDataPath: "/var/lib/longhorn"  # 数据存储路径
  
  # 备份配置（可选）
  backupTarget: "nfs://192.168.1.100:/backup/longhorn"  # 备份目标位置

# UI 配置
ui:
  service:
    type: LoadBalancer
    loadBalancerIP: 10.2.10.150  # 固定 IP 地址

# 磁盘配置
# 配置节点磁盘自动发现
disk:
  # 忽略系统盘
  ignorePattern: "/dev/sda|/dev/vda|/dev/nvme0n1"
  # 允许的磁盘类型
  allowPattern: "/dev/sd.*|/dev/vd.*|/dev/nvme.*"

7.2.2 使用 values.yaml 升级​

helm upgrade longhorn longhorn/longhorn \
  --namespace longhorn-system \
  -f values.yaml

7.3 磁盘分组和标签​

可以为磁盘添加标签，实现更精细的存储管理：

  1. 登录 Longhorn UI
  2. 导航到 "Nodes" 页面
  3. 点击要配置的节点
  4. 点击要配置的磁盘
  5. 点击 "Edit" 按钮
  6. 添加标签（例如：type=ssd）
  7. 点击 "Save" 按钮

然后在存储类中使用标签选择磁盘：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-ssd
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "3"
  diskSelector: "type=ssd"

8. 升级和卸载​

8.1 升级 Longhorn​

8.1.1 使用 Helm 升级​

helm repo update
helm upgrade longhorn longhorn/longhorn -n longhorn-system

8.1.2 使用 YAML 文件升级​

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

8.2 卸载 Longhorn​

8.2.1 使用 Helm 卸载​

helm uninstall longhorn -n longhorn-system
kubectl delete namespace longhorn-system

8.2.2 清理残留资源​

# 删除 CRD
kubectl delete crd -l app.kubernetes.io/instance=longhorn

# 删除存储类
kubectl delete storageclass longhorn

9. 故障排除​

9.1 常见问题​

9.1.1 Pod 无法挂载 Longhorn 卷​

  • 检查 open-iscsi 服务是否在所有节点上运行
  • 检查节点间网络连通性
  • 查看 Longhorn manager 日志获取详细错误信息

9.1.2 Longhorn UI 无法访问​

  • 检查 longhorn-frontend Service 是否正常运行
  • 检查防火墙设置，确保固定 IP 可以访问

9.1.3 卷处于降级状态​

  • 检查节点状态，确保所有节点都正常运行
  • 查看卷的副本状态，可能需要手动删除故障副本

9.2 诊断命令​

# 检查 Longhorn 状态
kubectl -n longhorn-system get longhornvolume

# 检查 Longhorn 节点状态
kubectl -n longhorn-system get longhornnode

# 查看 Longhorn manager 日志
kubectl -n longhorn-system logs longhorn-manager-<pod-id>

10. 最佳实践​

10.1 存储配置​

  • 使用 SSD 存储以获得更好的性能
  • 为 Longhorn 分配专用磁盘，避免与系统磁盘共享
  • 根据应用需求调整副本数量（性能与可靠性的权衡）

10.2 备份策略​

  • 定期创建卷备份
  • 将备份存储在与集群不同的位置（异地备份）
  • 测试从备份恢复的过程

10.3 监控和告警​

  • 集成 Prometheus 和 Grafana 监控 Longhorn 性能指标
  • 设置告警规则，监控卷状态、副本状态和存储使用率

10.4 节点管理​

  • 定期维护节点，确保系统和内核版本保持最新
  • 避免在运行关键应用的节点上进行维护操作

11. 参考资料​

12. 总结​

Longhorn 是一款轻量级、易用的 Kubernetes 分布式块存储解决方案，非常适合 K3s 集群。通过本指南，你已经了解了如何：

  • 完成安装前的准备工作，包括依赖安装和特定硬盘配置
  • 使用 Helm 快速部署 Longhorn 并配置固定 IP
  • 在 Pod 中使用 Longhorn 存储
  • 进行基本的管理操作
  • 在安装后添加特定硬盘和进行其他配置
  • 升级和卸载 Longhorn
  • 解决常见问题

Longhorn 提供了丰富的功能，包括快照、备份、恢复和卷克隆等，可以满足大多数应用场景的需求。在生产环境中，建议结合监控和告警系统，确保 Longhorn 集群的稳定运行。