在 Meshery 中导入并部署 ISCSI Pod Creation 设计模式:Kubernetes 连接 iSCSI 存储的实践指南
在 Meshery 中导入并部署 ISCSI Pod Creation 设计模式:Kubernetes 连接 iSCSI 存储的实践指南
导读
本文围绕 Meshery 官方设计模式目录(Catalog)中的 ISCSI pod creation 模式展开,讲解如何将 Kubernetes 集群与 iSCSI 存储设备对接,以实现可扩展的持久化存储解决方案,并支持直连(direct)与多路径(multipath)两种连接方式以及 CHAP 认证。通过阅读本文,你将掌握该 catalog 模式的元数据结构、底层 design 文件的组成方式、使用 mesheryctl design import 导入并部署该设计的完整流程,以及在实际生产环境中配置与运维 iSCSI 存储时必须注意的版本兼容、网络配置与性能监控要点。
一、模式概述:ISCSI pod creation 是什么
ISCSI pod creation 是 Meshery 设计模式目录中归属于 scaling(扩展) 类别的一个设计模式条目,其 catalog 元数据文件位于 docs/catalog/scaling/ae801c1f-8134-4f48-bc2e-d97c14f6a99c.md。该条目的核心定位可以概括为一句话(取自其 patternInfo 字段):
Connect Kubernetes clusters to iSCSI devices for scalable storage solutions, supporting direct or multipath connections with CHAP authentication.
即:将 Kubernetes 集群连接到 iSCSI 设备,构建可扩展的存储方案,支持直连或多路径连接,并支持 CHAP 认证。
在 Cloud Native 场景下,iSCSI(Internet Small Computer System Interface)允许 Kubernetes 中的 Pod 通过 IP 网络挂载远程块设备。相比本地磁盘,iSCSI 将存储与计算节点解耦,使得存储容量可以独立横向扩展,这正是该模式被归入 scaling 类别的原因。
该 catalog 条目的完整元数据信息如下:
| 字段 | 值 |
|---|---|
name |
ISCSI pod creation |
type |
scaling |
compatibility |
kubernetes |
patternId |
ae801c1f-8134-4f48-bc2e-d97c14f6a99c |
publishedVersion |
0.0.16 |
userId |
65a09154-3ae0-47c4-b19a-e0185ffb694f(shridhar kute) |
createdAt |
2024-08-15T19:39:40Z |
需要说明的是,该条目的 catalog 元数据中 version 字段标注为 0.0.16(即 publishedVersion),而其指向的 design 文件内部版本号为 0.0.181(见下文 design 文件分析),说明 catalog 页面展示的发布版本与实际设计内容版本由两套版本体系分别维护。
1.1 配套资源:design 文件与 artifacthub 元数据
与该 catalog 条目配套的底层资源存储在 docs/data/catalog/ 目录下,按 patternId/版本号 组织:
- 设计内容文件:docs/data/catalog/ae801c1f-8134-4f48-bc2e-d97c14f6a99c/0.0.16/design.yml
- 发行元数据文件:docs/data/catalog/ae801c1f-8134-4f48-bc2e-d97c14f6a99c/0.0.16/artifacthub-pkg.yml
artifacthub-pkg.yml 提供了该模式在 ArtifactHub 生态中展示所需的信息,其中几个关键字段值得关注:
| 字段 | 值 | 说明 |
|---|---|---|
name |
iscsi-pod-creation | 包名,使用短横线命名 |
displayName |
ISCSI pod creation | 展示名 |
description |
同 patternInfo | 与 catalog 元数据一致 |
license |
Apache-2.0 | 开源许可证 |
install |
mesheryctl design import -f |
官方推荐的安装/导入命令模板 |
readme |
见 1.2 节 | Caveats 与注意事项 |
1.2 使用注意(Caveats)
catalog 元数据的 patternCaveats 字段以及 artifacthub 的 readme 字段明确列出了使用该模式时必须注意的约束条件,原文如下:
Ensure compatibility of Kubernetes and iSCSI versions, configure network settings appropriately, and monitor performance and scalability of both storage and network infrastructure.
翻译并展开为三条核心注意事项:
- 版本兼容性(Version Compatibility):必须确保所使用的 Kubernetes 版本与 iSCSI 目标端(target)、发起端(initiator)软件版本互相兼容。iSCSI 相关内核模块、
open-iscsi工具链以及存储设备固件的版本差异可能导致挂载失败或数据面异常。 - 网络配置(Network Settings):iSCSI 完全依赖 IP 网络传输 SCSI 指令,必须正确配置网络设置。建议将 iSCSI 流量放在独立的 VLAN 或专用存储网络中,避免与业务流量争抢带宽;同时确认 MTU、路由、防火墙规则(默认 TCP 端口 3260)等网络参数。
- 性能与可扩展性监控(Performance & Scalability Monitoring):由于存储与网络双重参与 IO 路径,需要同时监控存储端(如 IOPS、吞吐、延迟、队列深度)和网络基础设施(如带宽利用率、丢包率、链路错误)的性能与扩展能力,及时发现瓶颈。
这些 caveats 来源于 docs/catalog/scaling/ae801c1f-8134-4f48-bc2e-d97c14f6a99c.md 的
patternCaveats字段,属于该模式的官方使用前提,请务必在生产环境遵循。
二、深入 design 文件:模式的实际内容载体
该 catalog 条目指向的 design 文件是 Meshery 设计模式(Design)的 JSON 序列化形式,完整内容如下:
{"id": "ae801c1f-8134-4f48-bc2e-d97c14f6a99c", "name": "ISCSI pod creation", "version": "0.0.181", "components": [], "relationships": [], "schemaVersion": "designs.meshery.io/v1beta1"}
文件路径:docs/data/catalog/ae801c1f-8134-4f48-bc2e-d97c14f6a99c/0.0.16/design.yml
2.1 Design 顶层结构解读
Meshery 的 Design 采用 designs.meshery.io/v1beta1 作为 schema 版本,顶层字段含义如下:
id:设计模式的全局唯一标识符(UUID),与 catalog 条目中的patternId完全一致,确保 catalog 页面与设计内容的一一对应。name:设计名称,与 catalog 的name字段一致,即 "ISCSI pod creation"。version:该设计内容自身的语义化版本号(0.0.181),用于追踪设计内容的迭代。components:设计中所包含的组件(Component)列表。当前仓库中该版本的components为空数组。relationships:设计内部组件之间的关系(Relationship)列表,当前为空数组。schemaVersion:Design 对象的 schema 版本,标识designs.meshery.io/v1beta1。
从源码结构看,components 与 relationships 两个字段是 Meshery 设计模式的核心数据结构:components 描述构成设计的各类云原生资源(如 Pod、PersistentVolume、VolumeAttachment 等),relationships 描述这些资源之间的依赖、网络、绑定等关系。本版本快照中两者均为空,说明该 catalog 条目主要承担“模式入口 + 说明文档”的定位——它通过 patternInfo/patternCaveats 承载 iSCSI 接入的完整知识,而将具体资源编排留给使用者在 Meshery UI 或 design 文件中组合完成。这一点也解释了为什么该条目属于 catalog 的 scaling 类设计模式集合,而非直接包含大量 Kubernetes 资源定义的样板。
2.2 从 Kubernetes 模型仓库看 iSCSI 组件支持
虽然该 design 文件当前版本未内嵌具体组件,但 Meshery 仓库内置的 Kubernetes 模型为 iSCSI 场景提供了完整的组件支撑。在 models/kubernetes/v1.35.0/v1.0.0/components/ 目录下,可以找到与 iSCSI 存储接入直接相关的 Kubernetes 原生组件:
- Pod(Pod.json):其
PodSpec的 volumes 定义支持iscsi卷类型,允许将 iSCSI 块设备直接挂载进 Pod。 - PersistentVolume(PersistentVolume.json):
PersistentVolumeSpec中定义了iscsi持久化卷源,支持以 PV/PVC 方式静态供给 iSCSI 存储。 - VolumeAttachment(VolumeAttachment.json):用于表达“将指定卷挂载到指定节点”的意图,是存储插件完成 attach 操作的核心对象。
以 Kubernetes 的 ISCSIPersistentVolumeSource 为例,在 Pod 或 PV 中使用 iSCSI 时,典型的字段包括:
| 字段 | 说明 |
|---|---|
targetPortal |
iSCSI 目标端的 IP 地址与端口,格式为 IP:port(默认 3260) |
iqn |
iSCSI Qualified Name,即目标端的限定名称 |
lun |
逻辑单元号,指定目标端上的块设备 |
fsType |
文件系统类型(如 ext4、xfs) |
readOnly |
是否只读挂载 |
chapAuthDiscovery / chapAuthSession |
分别启用 CHAP 发现与会话认证 |
secretRef |
引用保存 CHAP 用户名密码的 Secret |
initiatorName |
自定义发起端名称(可选) |
这一组件支撑正是该模式描述中"direct or multipath connections with CHAP authentication"得以落地的基础:通过 Meshery 的设计画布,你可以把上述组件拖拽组合,再配合 Relationship 定义(如 PV 与 PVC 的绑定、VolumeAttachment 与节点的挂载关系)完成完整的 iSCSI 存储接入设计。
三、实战:使用 mesheryctl 导入并部署该设计
根据 artifacthub 元数据中的 install 字段,官方推荐的导入命令模板为 mesheryctl design import -f。下面给出完整、可执行的实操流程。
3.1 前置条件
- 已安装并配置
mesheryctl(本仓库的 CLI 源码位于 mesheryctl 目录)。 - 已启动并运行 Meshery 服务(本仓库根目录提供 compose.yaml 及 Dockerfile,可参考 install 目录下的部署方式)。
- 本地已准备 iSCSI 目标端(Target)并可被 Kubernetes 节点访问,TCP 3260 端口网络可达。
3.2 获取设计文件
该 catalog 条目对应的 design 文件位于仓库内:
在实际使用中,你可以直接下载该 design 文件到本地,然后进行导入。
3.3 导入设计:mesheryctl design import
mesheryctl design import 命令用于将 Helm Charts、Kubernetes Manifest、Docker Compose 或 Meshery 设计文件导入为设计。命令定义位于 mesheryctl/internal/cli/root/design/import.go,其基本用法为:
mesheryctl design import -f [file/URL] -s [source-type] -n [name]
核心参数说明:
| 参数 | 必填 | 说明 |
|---|---|---|
-f, --file |
必填 | 本地文件路径或远程 URL(若为远程 URL,必须是可直接下载文件的直链,例如 GitHub 的 raw 链接)。支持 YAML、TGZ(仅 Helm)格式;若导入 Meshery Design 的 OCI 文件,也支持 OCI 格式 |
-s, --source-type |
可选 | 源类型,例如 "Kubernetes Manifest",用于标识输入文件的类型 |
-n, --name |
可选 | 导入后设计的名称 |
该命令的 Example 部分给出了三种典型调用方式(参见 import.go):
# 方式一:导入本地设计文件(自动识别类型)
mesheryctl design import -f design.yml
# 方式二:导入并指定设计名称
mesheryctl design import -f design.yml -n design-name
# 方式三:导入并指定源类型与名称
mesheryctl design import -f design.yml -s "Kubernetes Manifest" -n design-name
# 方式四:导入 tar 归档
mesheryctl design import -f design.tar
针对本 catalog 条目,假设已将 design 文件保存到本地,完整的导入命令如下:
mesheryctl design import -f docs/data/catalog/ae801c1f-8134-4f48-bc2e-d97c14f6a99c/0.0.16/design.yml -n iscsi-pod-creation
3.4 常见错误提示(源码佐证)
在 mesheryctl/internal/cli/root/design/error.go 中可以看到该命令的错误处理逻辑。最常见的错误是未提供 -f 参数,此时会输出如下提示:
Usage: mesheryctl design import -f [file/url] -s [source-type]
Example: mesheryctl design import -f ./pattern.yml -s "Kubernetes Manifest"
错误信息明确为 '[File | File Path | URL] not detected. The '-f' flag is missing or empty in the 'mesheryctl design import' command。这提醒我们在执行导入前,务必确认 -f 参数指向的文件确实存在且路径正确。
3.5 部署与后续管理
导入成功后,设计会出现在 Meshery 中。部署流程如下:
- 打开 Meshery 用户界面,进入 Designs(设计) 页面,找到导入的
iscsi-pod-creation设计。 - 在设计画布中补充 iSCSI 相关组件(Pod / PersistentVolume / VolumeAttachment 等,见 2.2 节)或加载你已有的完整设计。
- 关联目标 Kubernetes 环境后,点击 Deploy(部署) 执行部署。
- 部署完成后,通过 Meshery 的可观测性视图监控 iSCSI 卷挂载状态与工作负载运行情况。
四、CHAP 认证与直连/多路径连接说明
该模式描述中的三个关键技术点——直连、多路径、CHAP 认证——分别对应 iSCSI 接入的不同设计决策:
4.1 直连(Direct Connection)
直连是指每个 Kubernetes 节点(initiator)与 iSCSI 目标端建立一条 TCP 会话。其特点是拓扑简单、易于排障,适合中小规模部署或对单点故障容忍度要求不高的场景。在 Kubernetes 的 iSCSI 卷定义中,只需提供一个 targetPortal 与 iqn 即可完成直连配置。
4.2 多路径(Multipath Connection)
多路径通过在发起端与目标端之间建立多条 TCP 会话(通常经由不同网卡或不同网络路径),配合 DM-Multipath 实现链路冗余与 IO 负载均衡,从而提升可用性与吞吐。在 Kubernetes 场景下:
- 发起端节点需要安装并配置
multipath-tools,启用 multipathd 服务; - iSCSI 卷定义需在节点侧呈现为同一个多路径设备(如
/dev/mapper/mpathX); - 多路径通常要求目标端具备多个网络端口,且各路径指向同一
iqn与lun。
4.3 CHAP 认证
CHAP(Challenge Handshake Authentication Protocol)用于在 iSCSI 会话建立时验证发起端与目标端的身份,防止未授权设备接入存储。Kubernetes 的 iSCSI 卷支持两级 CHAP:
- 发现认证(Discovery CHAP):在目标发现阶段认证(对应
chapAuthDiscovery); - 会话认证(Session CHAP):在会话建立阶段认证(对应
chapAuthSession)。
用户名与密码通过 Kubernetes Secret 引用(对应 secretRef 字段)注入,避免明文写入卷定义。
注意:以上直连/多路径/CHAP 的具体实现细节属于 Kubernetes 与 iSCSI 生态的通用实践;在 Meshery 中,它们最终体现为 design 文件里组件的属性与 Relationship 编排。请结合 1.2 节 caveats,确保版本与网络配置满足多路径与 CHAP 的启用条件。
五、总结
ISCSI pod creation 是 Meshery Catalog 中面向 Kubernetes + iSCSI 存储扩展场景的官方设计模式条目,其核心价值体现在:
- 模式语义:以
patternInfo明确了"连接 Kubernetes 集群与 iSCSI 设备以构建可扩展存储、支持直连/多路径与 CHAP 认证"的完整技术主张; - 约束清单:以
patternCaveats给出了版本兼容、网络配置、性能与可扩展性监控三大使用前提; - 可执行入口:通过
artifacthub-pkg.yml中的install: mesheryctl design import -f打通了从 catalog 到 CLI 导入的完整链路; - 组件支撑:仓库内置的 Kubernetes 模型 提供了 Pod、PersistentVolume、VolumeAttachment 等 iSCSI 相关组件,供你在设计画布中组合完整方案。
无论你是要在 Meshery 中快速尝试 iSCSI 存储接入,还是希望基于该模式构建生产级的可扩展存储设计,都可以按照本文第三部分的命令流程完成导入,并严格遵循第一部分列出的 caveats 进行配置与运维。
关键文件索引
| 资源 | 仓库相对路径 |
|---|---|
| Catalog 元数据 | docs/catalog/scaling/ae801c1f-8134-4f48-bc2e-d97c14f6a99c.md |
| Design 内容文件 | docs/data/catalog/ae801c1f-8134-4f48-bc2e-d97c14f6a99c/0.0.16/design.yml |
| ArtifactHub 元数据 | docs/data/catalog/ae801c1f-8134-4f48-bc2e-d97c14f6a99c/0.0.16/artifacthub-pkg.yml |
| CLI 导入命令实现 | mesheryctl/internal/cli/root/design/import.go |
| CLI 导入错误处理 | mesheryctl/internal/cli/root/design/error.go |
| Kubernetes 组件模型(iSCSI 相关) | models/kubernetes/v1.35.0/v1.0.0/components/ |