Longhorn 官方 Helm Chart 部署指南：Kubernetes 分布式块存储的安装、配置与卸载

云原生存储高可用容器编排【免费下载链接】longhornCloud-Native distributed storage built on and for Kubernetes项目地址https://gitcode.com/gh_mirrors/lo/longhorn点击查看免费下载导读本文以 Longhorn 项目仓库中的 chart/app-readme.md 与 chart/README.md 为核心系统讲解如何通过官方 Helm Chart 在 Kubernetes 集群中部署 Longhorn——一个为每个卷创建专用存储控制器、跨多节点同步复制数据的分布式块存储系统。读完本文你将掌握 Longhorn Chart 的完整安装/卸载流程、前置条件检查、核心 Values 配置项的语义与默认值以及面向生产环境的关键调优参数能够独立完成一套可用、可维护的 Longhorn 持久化存储集群的搭建与升级。Longhorn 是什么每卷独立控制器的分布式块存储Longhorn 是一个轻量、可靠、易于使用的 Kubernetes 分布式块存储系统。部署完成后Kubernetes 工作负载即可直接使用 Longhorn 提供的 PersistentVolume。其核心架构特点见 chart/app-readme.md包括每卷专用存储控制器Longhorn 为每一个卷创建一个独立的存储控制器卷的 I/O 路径、副本管理彼此隔离避免单点集中瓶颈多副本同步复制卷会被同步复制到分布在多个节点上的多个副本中任一副本所在节点故障时其余副本仍可继续提供服务原生 Kubernetes 编排存储控制器与副本本身也是由 Kubernetes 调度的容器天然获得集群的资源管理、调度与故障恢复能力快照与备份支持卷快照、备份以及定时Recurring快照与备份任务调度。从 Chart 元数据chart/Chart.yaml可以看到该 Chart 的appVersion为v1.12.0-devkubeVersion要求1.34.0-0关键词覆盖storage、block、iscsi、nfs等这说明当前版本面向较新的 Kubernetes API 能力。安装前必须注意的两条硬性规则官方文档明确强调了两个安装约束违反任何一条都会带来部署问题必须安装到longhorn-system命名空间Chart 内的许多组件如longhorn-storageclassConfigMap、longhorn-default-settingConfigMap、webhook 服务等默认按longhorn-system命名空间硬编码或假定其存在安装到其他命名空间会导致组件行为异常不支持版本降级Longhorn 不支持从高版本降级到低版本升级前请确认目标版本高于当前版本并遵循官方升级路径。此外官方还建议使用Helm 3进行安装与升级Helm 2 已不再支持见 chart/README.md 中的 Note 说明。环境前置条件在开始安装之前请逐项核对集群环境详见 chart/README.md 的 Prerequisites 一节与 Kubernetes 兼容的容器运行时Docker v1.13、containerd v1.3.7 等Kubernetes 版本 v1.34与 chart/Chart.yaml 中kubeVersion: 1.34.0-0一致集群所有节点上必须安装bash、curl、findmnt、grep、awk和blkid集群所有节点上必须安装open-iscsi且iscsid守护进程处于运行状态。对于 GKE建议使用 Ubuntu 作为 Guest OS 镜像因为其默认已内置open-iscsi。快速安装三行命令完成部署官方推荐的安装流程如下来自 chart/README.md# 1. 添加 Longhorn Chart 仓库 helm repo add longhorn https://charts.longhorn.io # 2. 更新本地 Chart 信息 helm repo update # 3. 先创建 longhorn-system 命名空间再安装 Chart kubectl create namespace longhorn-system helm install longhorn longhorn/longhorn --namespace longhorn-system安装完成后Chart 的 NOTES.txt 会提示Longhorn 已安装到集群请等待数分钟让 CSI 相关 Deployment、Engine Images、Instance Managers 等组件完成初始化并引导前往官方文档查看更多信息。安装完成后发生什么从 Chart 模板结构chart/templates 目录可以还原出安装后的资源布局控制面组件longhorn-managerDaemonSet每个节点一个、longhorn-uiDeployment默认 2 副本、longhorn-driver-deployerDeployment、longhorn-global-managerDeployment默认 3 副本见 deployment-global-manager.yaml 对应的 ValuesCRD 与权限通过 crds.yaml、clusterrole.yaml、clusterrolebinding.yaml 安装 Longhorn 的 CustomResourceDefinition 及集群级 RBAC配置载体通过 default-setting.yaml 生成longhorn-default-settingConfigMap承载defaultSettings的值通过 storageclass.yaml 生成longhorn-storageclassConfigMap承载默认 StorageClass 的定义服务入口longhorn-managerREST APITCP/9500、longhorn-ui、longhorn-admission-webhookTCP/9502、longhorn-recovery-backendTCP/9503等 Service见 services.yaml升级/卸载钩子preupgrade-job.yamlpre-upgradehook运行longhorn-manager pre-upgrade与 uninstall-job.yamlpre-deletehook运行longhorn-manager uninstall --force。在 OpenShift 上安装Chart 内置了 OpenShift 集成开关openshift.enabled启用后会在 deployment-ui.yaml 中额外创建 OpenShiftRoute默认名longhorn-uiTLS 终止方式为reencrypt并配置 serving-cert 注解同时可通过 ocp-readme.md 获取针对 OpenShift 的专门说明。卸载与删除保护机制Longhorn 卸载不是简单的helm uninstall因为卷数据、备份等资源需要被有意识地清理。官方流程见 chart/README.md# 1. 设置删除确认标记防止误删的保护机制 kubectl -n longhorn-system patch -p {value: true} --typemerge lhs deleting-confirmation-flag # 2. 卸载 Helm Release helm uninstall longhorn -n longhorn-system # 3. 删除命名空间 kubectl delete namespace longhorn-system其中第一步对应defaultSettings.deletingConfirmationFlag这一系统设置——它用于防止 Longhorn 被意外卸载。同时卸载过程由 uninstall-job.yaml 中的pre-deletehook Job 执行longhorn-manager uninstall --force负责清理 Longhorn 管理的相关资源后再放行 Helm 卸载。Kubernetes v1.25从 Pod Security Policy 迁移到 Pod Security AdmissionKubernetes 从 v1.25 起从 API 中移除了 Pod Security PoliciesPSP。官方给出了明确的迁移要求chart/README.md 的 Upgrading to Kubernetes v1.25 一节升级到 Kubernetes v1.25 之前或在 v1.25 集群上全新安装时如果此前enablePSP为true必须先将 Chart 原地升级为enablePSP设为false这也是该值的默认值。设为false后Chart 会自动从集群中清除它此前创建的 PSP 资源警告如果先升级集群到 v1.25 再通过helm upgrade移除 PSP即使你手动清理了资源Helm Release 会进入损坏状态导致后续helm uninstall、helm upgrade等操作全部失效此时可能需要手动清理 Helm Release 的 SecretPSP 的替代方案是 Kubernetes 的Pod Security Admission需要为 Longhorn 所在的 release 命名空间配置合适的 Pod Security Standards。Chart 中的 psp.yaml 与 validate-psp-install.yaml 模板即为该兼容逻辑的落地实现。Values 配置详解从入门到生产调优Chart 的全部可配置项定义在 chart/values.yaml 中共 798 行官方 README 也以表格形式汇总了每个键的类型、默认值与语义。下面按主题分组讲解最常用的配置。全局与私有镜像仓库配置global / privateRegistry / imageglobal.imageRegistry全局镜像仓库覆盖配合离线/内网环境使用global.imagePullSecrets全局覆盖镜像拉取 Secretglobal.tolerations/global.nodeSelector作用于用户部署组件Longhorn Manager、Longhorn UI、Longhorn Driver Deployerglobal.timezone为所有 Longhorn 工作负载设置容器时区TZ 环境变量image.longhorn.*分别指定 engine、manager、ui、instanceManager、shareManager、backingImageManager、supportBundleKit 的 registry/repository/tag。当前版本默认 tag 多为master-head开发版支持 bundle kit 为v0.0.93image.csi.*CSI 侧车镜像attacherv4.12.0、provisionerv6.3.0、resizerv2.2.1、snapshotterv8.6.0、nodeDriverRegistrarv2.17.0、livenessProbev2.19.0image.pullPolicy默认IfNotPresent作用于所有用户部署组件私有仓库离线安装privateRegistry.createSecret、privateRegistry.registryUrl、privateRegistry.registryUser、privateRegistry.registryPasswd、privateRegistry.registrySecret用于在 air-gapped 环境从私有镜像仓库拉取镜像由 registry-secret.yaml 模板生成 Secret。默认 StorageClass 配置persistence默认 StorageClass 由 storageclass.yaml 模板以 ConfigMap 形式生成provisioner: driver.longhorn.io并支持allowVolumeExpansion: true在线扩容。常用参数键默认值说明persistence.createStorageClasstrue是否创建默认 StorageClass ConfigMappersistence.defaultClasstrue是否将longhornStorageClass 标记为集群默认写入storageclass.kubernetes.io/is-default-class注解persistence.defaultClassReplicaCount3默认副本数映射为参数numberOfReplicaspersistence.defaultFsTypeext4默认文件系统类型persistence.defaultMkfsParams传给 mkfs 的额外参数persistence.defaultDataLocalitydisabled数据本地性可选disabled/best-effort映射为参数dataLocalitypersistence.reclaimPolicyDelete回收策略可选Retain/Deletepersistence.volumeBindingModeImmediate卷绑定模式可选Immediate/WaitForFirstConsumerpersistence.migratablefalse是否允许卷在节点间在线迁移RWX 相关persistence.disableRevisionCountertrue关闭修订计数器卷恢复salvage时通过volume-head-xxx.img的文件大小与修改时间来选择恢复用副本persistence.dataEnginev1数据引擎版本可选v1/v2v2 基于 SPDKpersistence.backupTargetNamedefault默认 StorageClass 关联的备份目标persistence.nfsOptionsRWX 卷的 NFS 挂载选项persistence.unmapMarkSnapChainRemovedignored文件系统 trim 时是否自动移除快照链可选ignored/enabled/disabled此外还支持defaultDiskSelector磁盘标签选择器如nvme,sata、defaultNodeSelector节点标签选择器如storage,fast、recurringJobSelector定时任务选择器如[{name:backup, isGroup:true}]、backingImage指定后端镜像及其数据源类型/参数/期望 SHA-512 校验和、shareManagerNodeSelector/shareManagerTolerationsRWX 共享管理器 Pod 的调度约束等高级选项。系统默认设置defaultSettingsdefaultSettings段会在安装时写入longhorn-default-settingConfigMap由 default-setting.yaml 渲染键名采用 kebab-case例如default-replica-count、storage-over-provisioning-percentage作为 Longhorn 各 CRD 控制器的系统级默认值。安装后仍可通过 Longhorn UI 或直接编辑 Setting CR 修改。高频调优项包括容量规划storageOverProvisioningPercentage默认100允许超卖比例、storageMinimalAvailablePercentage默认25磁盘剩余容量低于该比例则不可调度、storageReservedPercentageForDefaultDisk新节点默认磁盘预留比例副本策略defaultReplicaCount默认{v1:3,v2:3}、replicaAutoBalance、replicaSoftAntiAffinity默认关闭、replicaZoneSoftAntiAffinity、replicaDiskSoftAntiAffinity默认开启、concurrentReplicaRebuildPerNodeLimit调度与故障处理disableSchedulingOnCordonedNode默认开启、nodeDrainPolicy、nodeDownPodDeletionPolicy、autoSalvage默认开启自动抢救全部副本故障的卷、detachManuallyAttachedVolumesWhenCordoned备份与快照backupConcurrentLimit、restoreConcurrentLimit、backupCompressionMethod、failedBackupTTL、snapshotMaxCount2~250、snapshotCountWarningThreshold、snapshotDataIntegrity及其Cronjob表达式V2 数据引擎SPDK专项v2DataEngine、dataEngineMemorySize默认{v2:2048}MiB、dataEngineCPUMask默认0x3、dataEngineNumberOfCPUCores需 kubelet 静态 CPU 策略、dataEngineHugepageEnabled、dataEngineInterruptModeEnabled、dataEngineIobufLargePoolSize/dataEngineIobufSmallPoolSizeiobuf 缓冲池只能在spdk_tgt启动时配置、defaultUblkQueueDepth/defaultUblkNumberOfQueueUblk 前端队列配置、defaultNvmeTcpNrIoQueuesNVMe-TCP 前端 I/O 队列数网络专项storageNetwork集群内存储专用网络、endpointNetworkForRWXVolumeRWX 挂载专用网络只能在所有 RWX 卷分离后修改、csiAllowedTopologyKeysCSI 透传拓扑键、csiStorageCapacityTracking运维治理taintToleration系统托管组件容忍度kubectl taint语法分号分隔、systemManagedComponentsNodeSelector、priorityClass默认longhorn-critical、orphanResourceAutoDeletion孤儿资源自动清理可用项replica-data;instance、kubernetesClusterAutoscalerEnabled、managerUrl注意该值持久化于 Setting CR删除 Helm values 不会自动清除需在 UI/kubectl 中手动置空。网络策略networkPoliciesnetworkPolicies.enabled总开关默认falsenetworkPolicies.restrictInternalTraffic默认true开启后仅授权组件之间可互相通信策略模板位于 network-policies 目录含 manager、webhook、instance-manager、backing-image-manager、recovery-backend、ui-frontend 等策略文件networkPolicies.type发行版适配可选k3s/rke2/rke1networkPolicies.kubeAPIServerSourceCIDRs允许访问 Longhorn admission webhook 的 API Server 源 CIDRnetworkPolicies.v1DataEngineInitiatorSourceCIDRsV1 iSCSI initiator 流量源 CIDR默认放行可达 TCP/3260 的任何来源networkPolicies.metricsScrapeMetrics即metricsScrapeSources在restrictInternalTraffic开启时允许抓取 Longhorn Manager TCP/9500 指标的来源。注意TCP/9500 同时承载 Longhorn Manager REST API官方建议每个条目尽量窄化如同时给出namespaceSelector与podSelector避免单独放行整个命名空间。组件副本与高可用longhornManager / longhornUI / longhornGlobalManager / csilonghornManager.updateStrategy.rollingUpdate.maxUnavailable默认100%与升级流程匹配先移除旧 Manager 再启动新 Manager如需滚动更新行为可覆盖longhornUI.replicas默认2longhornUI.podDisruptionBudget默认关闭开启后仅在副本数 1 时生效longhornUI.topologySpreadConstraints可保证滚动更新期间副本跨拓扑域分布longhornGlobalManager.replicas默认3一个副本为 active leader其余为 warm standby该组件承载集群级 Pod 控制器KubernetesPVController、KubernetesPodController内存占用随集群 Pod 数量增长csi.attacherReplicaCount/csi.provisionerReplicaCount/csi.resizerReplicaCount/csi.snapshotterReplicaCountCSI 侧车副本数默认 3csi.podAntiAffinityPreset默认softcsi.allowControllerSecretAccess默认开启关闭仅适用于无控制器侧 Secret 参数的场景加密卷必须保留 Secret 引用csi.volumeGroupSnapshotEnabled启用 CSI VolumeGroupSnapshot 前必须先安装groupsnapshot.storage.k8s.ioCRD。服务、Ingress 与 Gateway APIservice / ingress / httprouteservice.ui.typeLonghorn UI 服务类型可选ClusterIP/NodePort/LoadBalancer/Rancher-Proxyservice.manager.nodePort与service.ui.nodePort未指定时 Longhorn 会在 30000~32767 之间自动选空闲端口trafficDistribution可设为PreferSameZone/PreferSameNodeingress.enabled默认false为 UI 生成 Ingress默认 host 为sslip.io支持extraHosts多 FQDN 的 TLS SAN、tls/tlsSecret默认longhorn.local-tls、pathType默认ImplementationSpecific为向后兼容保留httproute.enabled默认false使用 Gateway API 生成 HTTPRoute支持parentRefs、hostnames、filters如 Traefik Middleware 扩展引用、pathTypeExact/PathPrefix。监控与可观测性metricsmetrics.serviceMonitor.enabled默认false启用后由 servicemonitor.yaml 为 Longhorn Manager 创建 Prometheus ServiceMonitor支持interval、scrapeTimeout、relabelings、metricRelabelings、sampleLimit等标准配置。其他关键开关enablePSP默认false仅对 Kubernetes 1.25 及更早版本且启用了内置 Pod Security admission 的集群有意义preUpgradeChecker.jobEnabled/preUpgradeChecker.upgradeVersionCheck默认均true执行升级前检查使用 Argo CD 等 GitOps 方案安装时建议关闭jobEnablednamespaceOverride将 Longhorn 作为子 Chart 且 release 命名空间不是longhorn-system时的命名空间覆盖extraObjects追加任意额外资源清单annotations为 Longhorn Manager DaemonSet Pod 追加注解。结合源码理解配置生效链路上述 Values 并非写入即生效的黑盒安装时 Helm 通过模板把配置物化到集群内两类载体上StorageClass 参数persistence.*相关值被 storageclass.yaml 渲染为longhorn-storageclassConfigMap 中的storageclass.yaml数据段最终由 Longhorn 的 CSI Provisionerdriver.longhorn.io在动态供给卷时读取映射为numberOfReplicas、dataLocality、diskSelector、nodeSelector、backingImage*、recurringJobSelector、dataEngine等 StorageClass 参数系统级 SettingdefaultSettings.*被 default-setting.yaml 逐键渲染为longhorn-default-settingConfigMap 中的 kebab-case 键值如default-replica-count、storage-over-provisioning-percentage、manager-urlLonghorn Manager 启动时读取该 ConfigMap 初始化各 Setting CR进而驱动卷控制器、副本调度器、Instance Manager 等组件的实际行为。理解了这条链路就能明白为什么部分系统设置如 V2 引擎的dataEngineCPUMask、iobuf 池大小需要重启 Instance Manager 甚至要求卷全部分离后才能生效——它们必须在spdk_tgt启动阶段以生成 JSON 配置的方式注入。升级注意事项不支持降级升级前确认目标 Chart 版本高于当前版本升级前检查默认启用的preUpgradeChecker会以pre-upgradehook Job见 preupgrade-job.yaml执行longhorn-manager pre-upgrade校验升级路径与版本兼容性GitOps 场景如 Argo CD下关闭preUpgradeChecker.jobEnabled以避免 hook 干扰PSP 迁移若集群将升级到 Kubernetes v1.25务必先执行带enablePSPfalse的helm upgrade否则 Helm Release 可能损坏V2 引擎滚动升级allowInstanceManagerAutomaticUpgrade、instanceManagerUpgradeStartTimeRFC3339 格式、instanceManagerUpgradeTimeout控制 V2 Instance Manager 的自动滚动升级行为。总结Longhorn 官方 Helm Chart 以每卷独立控制器 多副本同步复制为核心模型为 Kubernetes 提供了可快照、可备份、可定时任务的分布式块存储能力。安装时务必遵守longhorn-system命名空间约束与不支持降级的版本纪律通过 chart/values.yaml 中的persistence、defaultSettings、networkPolicies、longhornManager/longhornUI/longhornGlobalManager等配置段可以在镜像仓库、默认 StorageClass、副本策略、容量规划、网络隔离、高可用与监控等维度完成从开箱即用到生产级调优的全部配置工作。对于离线环境、OpenShift、RWX 工作负载、SPDK V2 数据引擎等场景Chart 也提供了对应的内置开关与模板支撑建议结合 chart/README.md 与 chart/ocp-readme.md 进一步深入。赞分享云原生存储高可用容器编排【免费下载链接】longhornCloud-Native distributed storage built on and for Kubernetes项目地址https://gitcode.com/gh_mirrors/lo/longhorn点击查看免费下载相关推荐TREK 的 Kubernetes 部署指南使用官方 Helm Chart 安装与配置TREK 的 Kubernetes 部署指南使用官方 Helm Chart 安装与配置 导读 TREK 是一款自托管的旅行规划应用支持实时协作、交互式地图、后端前端MCP 服务AI 应用Longhorn Helm Chart 完整部署与配置指南安装、卸载、values 参数与源码级解析Longhorn Helm Chart 完整部署与配置指南安装、卸载、values 参数与源码级解析 本文以 Longhorn 官方 Helm Chart云原生存储高可用容器编排Quickwit on Kubernetes使用官方 Helm Chart 部署与配置指南Quickwit on Kubernetes使用官方 Helm Chart 部署与配置指南 导读 本文介绍如何在 Kubernetes 集群中通过官方 Qui搜索引擎可观测性日志分析链路追踪后端全文检索上一篇Win11Debloat轻量智能的系统净化工具让Windows 11重获新生下一篇OpCore-Simplify智能构建黑苹果EFI的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考