Kubernetes iSCSI 持久化卷接入实战:基于 open-iscsi 与 multipathd 的 Pod 存储配置指南

原创2026-10-06 22:20:041,935 阅读
文章标签:示例工程

Kubernetes iSCSI 持久化卷接入实战:基于 open-iscsi 与 multipathd 的 Pod 存储配置指南

本篇指南以 Kubernetes 官方示例仓库中的 iSCSI 卷示例文档 为核心,完整讲解如何在 Kubernetes 集群中通过内置 iSCSI 卷插件,将外部 iSCSI Target 的 LUN 挂载为 Pod 持久化存储。你将掌握 targetPortal、iqn、lun、fsType、portals、iscsiInterface 等核心字段的配置方法,学会启用 CHAP 双向认证,并了解如何通过 mount、docker inspect 等命令验证挂载结果——覆盖从「准备 iSCSI Target」到「Pod 内看到数据卷」的完整链路。

功能概览:Kubernetes iSCSI 卷插件能做什么

Kubernetes 的 iSCSI 实现基于 Linux 主机上的 open-iscsi 与 multipathd 两个组件工作:open-iscsi 负责发起 iSCSI 会话并发现 Target,multipathd 负责在存在多条存储路径时完成多路径(MPIO)聚合。根据 官方示例文档,当前实现支持以下特性:

  • 连接单个 Portal:通过 targetPortal 指定 iSCSI Target 的 IP 与端口(默认 3260),并可通过 portals 字段声明同一 IQN 下的多个 Portal 以实现多路径。
  • 直接挂载或经 multipathd 挂载:非多路径场景下设备直接以裸盘(如 /dev/sdb)挂载;启用 MPIO 后则聚合为 /dev/mapper/mpathX 设备挂载。
  • 自动格式化与分区:对任何新接入的设备,Kubernetes 会在首次挂载时自动完成格式化和分区。
  • CHAP 认证:支持发现阶段(discovery)与会话阶段(session)的单向或双向 CHAP 认证,凭据通过专用 Secret 注入。

前置条件:先准备一个可用的 iSCSI Target

该示例要求环境中已存在一个可正常连接的 iSCSI Target,Kubernetes 侧只是扮演发起方(initiator)的角色。若当前没有现成 Target,可以在 Linux 主机上通过软件方式搭建,官方文档给出了三条参考路径:

  1. 在 Fedora 上搭建 iSCSI Target(配置 target 侧导出 LUN);
  2. 在 Fedora 上安装并配置 iSCSI initiator(节点侧发起连接);
  3. 若需要 MPIO(多路径)支持,安装并配置 multipathd(通常指 RHEL/CentOS 系发行版上的 device-mapper-multipath)。

上述链接均为社区教程且已被归档。实际环境中,只要节点能够用 iscsiadm 正常发现并登录 Target(iscsiadm -m discovery -t sendtargets -p <portal> 能看到目标 IQN),即可满足本示例的前提。

此外还有一处需要注意:如果按照社区教程操作时对设备进行了分区,那么请格外留意——iSCSI 卷插件目前不支持直接使用分区。正确的做法是:将设备格式化为单个分区,或保持设备为裸盘(raw),让 Kubernetes 在首次挂载时自行完成分区与格式化。

核心示例:创建挂载 iSCSI 持久化存储的 Pod

仓库中的 iscsi.yaml 是一个完整可用的示例,展示了 Pod 内联声明 iSCSI 卷的最基本用法:

---
apiVersion: v1
kind: Pod
metadata:
  name: iscsipd
spec:
  containers:
  - name: iscsipd-rw
    image: kubernetes/pause
    volumeMounts:
    - mountPath: "/mnt/iscsipd"
      name: iscsipd-rw
  volumes:
  - name: iscsipd-rw
    iscsi:
      targetPortal: 10.0.2.15:3260
      portals: ['10.0.2.16:3260', '10.0.2.17:3260']
      iqn: iqn.2001-04.com.example:storage.kube.sys1.xyz
      lun: 0
      fsType: ext4
      readOnly: true

其中 volumes[].iscsi 是 iSCSI 卷的核心配置块,各字段含义如下:

字段 含义 说明
targetPortal 目标 Portal 地址 iSCSI Target 的 IP 地址,若端口不是默认的 3260,需以 IP:端口 形式显式写出
portals 其他 Portal 列表 当同一个 IQN 对应多个 Target Portal 时,在此列出其余 Portal 的 IP,供多路径使用
iqn Target 的 IQN iSCSI 限定名(iSCSI Qualified Name),用于唯一标识 Target,例如 iqn.2001-04.com.example:storage.kube.sys1.xyz
lun 逻辑单元号 要挂载的 LUN 编号,示例中为 0
fsType 文件系统类型 LUN 上已创建(或将由 Kubernetes 创建)的文件系统类型,示例为 ext4
readOnly 是否只读 布尔值,true 表示以只读方式挂载

无需提供任何 initiator 信息(如 initiator IQN 或 initiator IP),Kubernetes 会使用节点自身的 iSCSI initiator 配置发起连接。

使用非 TCP 传输:iscsiInterface

默认情况下 open-iscsi 使用 TCP 传输。如果你希望使用 iSCSI 卸载卡(offload card) 或其他非 TCP 传输,则需要先在节点上配置一个 iSCSI interface,并在 Pod 的 iscsi 配置块中通过 iscsiInterface 字段显式引用它:

    iscsi:
      targetPortal: 10.0.2.15:3260
      iqn: iqn.2001-04.com.example:storage.kube.sys1.xyz
      lun: 0
      fsType: ext4
      readOnly: true
      iscsiInterface: eth2

关于 interface 命名需要特别说明:open-iscsi 中该参数对应 iface.iscsi_ifacename,当通过 iscsiadm 生成时,默认命名格式为 transport_name.hwaddress(例如 tcp.00:0c:29:xx:xx:xx)。详细的 interface 配置方法请参考 open-iscsi 与 OpenStack 的 iscsi-iface 配置文档(两者均对 iscsiadm -m iface 的用法有系统说明)。

CHAP 认证:为发现与会话阶段启用安全认证

iSCSI 环境通常需要 CHAP 认证来保护 Target 资源。在 Pod 的 iscsi 配置块中,通过三个字段组合即可启用:

  • chapAuthDiscovery:设为 true 则启用发现阶段的 CHAP 认证;
  • chapAuthSession:设为 true 则启用会话阶段的 CHAP 认证;
  • secretRef:引用存放 CHAP 凭据的 Secret 名称。

仓库中的 iscsi-chap.yaml 是完整的带认证示例:

---
apiVersion: v1
kind: Pod
metadata:
  name: iscsipd
spec:
  containers:
  - name: iscsipd-ro
    image: kubernetes/pause
    volumeMounts:
    - mountPath: "/mnt/iscsipd"
      name: iscsivol
  volumes:
  - name: iscsivol
    iscsi:
      targetPortal: 127.0.0.1
      iqn: iqn.2015-02.example.com:test
      lun: 0
      fsType: ext4
      readOnly: true
      chapAuthDiscovery: true
      chapAuthSession: true
      secretRef:
         name: chap-secret

CHAP Secret 的结构与键映射

CHAP 凭据必须以专用 Secret 承载,其 type 必须是 kubernetes.io/iscsi-chap,且包含 8 个固定键,分别对应发现与会话两个阶段各自的单向/双向认证凭据。仓库中的 chap-secret.yaml 给出了完整结构:

---
apiVersion: v1
kind: Secret
metadata:
  name: chap-secret
type: "kubernetes.io/iscsi-chap"
data:
  discovery.sendtargets.auth.username: dXNlcg==
  discovery.sendtargets.auth.password: ZGVtbw==
  discovery.sendtargets.auth.username_in: bXVzZXI=
  discovery.sendtargets.auth.password_in: bXBhc3M=
  node.session.auth.username: dXNlcm5hbWU=
  node.session.auth.password: cGFzc3dvcmQ=
  node.session.auth.username_in: bXVzZXIy
  node.session.auth.password_in: bXBhc3My

这些键与 Open-iSCSI initiator 侧配置文件(iscsid.conf)中使用的键一一对应,语义如下:

Secret 键 对应阶段 含义
discovery.sendtargets.auth.username 发现 发起方(outgoing)用户名
discovery.sendtargets.auth.password 发现 发起方(outgoing)密码
discovery.sendtargets.auth.username_in 发现 目标方(incoming)用户名,用于双向 CHAP
discovery.sendtargets.auth.password_in 发现 目标方(incoming)密码,用于双向 CHAP
node.session.auth.username 会话 发起方(outgoing)用户名
node.session.auth.password 会话 发起方(outgoing)密码
node.session.auth.username_in 会话 目标方(incoming)用户名,用于双向 CHAP
node.session.auth.password_in 会话 目标方(incoming)密码,用于双向 CHAP

data 字段的值必须为 base64 编码。以上述示例为准:dXNlcg== 解码为 user,ZGVtbw== 解码为 demo,即发现阶段使用 user/demo;会话阶段 dXNlcm5hbWU= / cGFzc3dvcmQ= 解码为 username/password,incoming 方向对应 muser/mpass 与 muser2/mpass2。实际部署时请替换为你自己的凭据。

创建 CHAP Secret 的命令

原文档中给出的创建命令为:

# kubectl create -f examples/volumes/iscsi/chap-iscsi.yaml

注意原文档此处引用的文件名存在笔误——仓库中实际存放 CHAP Secret 的文件是 chap-secret.yaml(对应本仓库路径为 _archived/volumes/iscsi/chap-secret.yaml)。请先创建 CHAP Secret,再创建使用它的 iSCSI 卷与 Pod,正确的命令应为:

kubectl create -f _archived/volumes/iscsi/chap-secret.yaml

部署与验证:从创建 Pod 到确认挂载

1. 创建 Pod

编写好 Pod 配置后,在 Kubernetes 集群上执行:

kubectl create -f ./your_new_pod.yaml

使用仓库中的示例文件:

# kubectl create -f _archived/volumes/iscsi/iscsi.yaml
# kubectl get pods
NAME      READY     STATUS    RESTARTS   AGE
iscsipd   2/2       RUNNING   0           2m

原文档中的验证输出展示的是一个同时包含 iscsipd-rw 与 iscsipd-ro 两个容器的 Pod 变体(对应 READY 列为 2/2)。仓库当前提供的 iscsi.yaml 为单容器(iscsipd-rw)版本,iscsi-chap.yaml 则为单容器(iscsipd-ro)版本——READY 列应与你实际定义的容器数量一致。

2. 在节点上验证挂载输出

登录运行该 Pod 的 Kubernetes 节点,执行 mount | grep kub。对未启用 MPIO 的设备,输出形如:

# mount |grep kub
/dev/sdb on /var/lib/kubelet/plugins/kubernetes.io/iscsi/10.0.2.15:3260-iqn.2001-04.com.example:storage.kube.sys1.xyz-lun-0 type ext4 (rw,relatime,data=ordered)
/dev/sdb on /var/lib/kubelet/pods/f527ca5b-6d87-11e5-aa7e-080027ff6387/volumes/kubernetes.io~iscsi/iscsipd-rw type ext4 (ro,relatime,data=ordered)
/dev/sdc on /var/lib/kubelet/plugins/kubernetes.io/iscsi/10.0.2.16:3260-iqn.2001-04.com.example:storage.kube.sys1.xyz-lun-0 type ext4 (rw,relatime,data=ordered)
/dev/sdc on /var/lib/kubelet/pods/f527ca5b-6d87-11e5-aa7e-080027ff6387/volumes/kubernetes.io~iscsi/iscsipd-rw type ext4 (rw,relatime,data=ordered)
/dev/sdd on /var/lib/kubelet/plugins/kubernetes.io/iscsi/10.0.2.17:3260-iqn.2001-04.com.example:storage.kube.sys1.xyz-lun-0 type ext4 (rw,relatime,data=ordered)
/dev/sdd on /var/lib/kubelet/pods/f527ca5b-6d87-11e5-aa7e-080027ff6387/volumes/kubernetes.io~iscsi/iscsipd-rw type ext4 (rw,relatime,data=ordered)

而启用了 MPIO 的节点上,裸盘设备会被 multipathd 聚合为 /dev/mapper/mpathX,输出形如:

# mount |grep kub
/dev/mapper/mpatha on /var/lib/kubelet/plugins/kubernetes.io/iscsi/10.0.2.15:3260-iqn.2001-04.com.example:storage.kube.sys1.xyz-lun-0 type ext4 (rw,relatime,data=ordered)
/dev/mapper/mpatha on /var/lib/kubelet/pods/f527ca5b-6d87-11e5-aa7e-080027ff6387/volumes/kubernetes.io~iscsi/iscsipd-ro type ext4 (ro,relatime,data=ordered)
/dev/mapper/mpathb on /var/lib/kubelet/plugins/kubernetes.io/iscsi/10.0.2.16:3260-iqn.2001-04.com.example:storage.kube.sys1.xyz-lun-0 type ext4 (rw,relatime,data=ordered)
/dev/mapper/mpathb on /var/lib/kubelet/pods/f527ca5b-6d87-11e5-aa7e-080027ff6387/volumes/kubernetes.io~iscsi/iscsipd-rw type ext4 (rw,relatime,data=ordered)
/dev/mapper/mpathc on /var/lib/kubelet/plugins/kubernetes.io/iscsi/10.0.2.17:3260-iqn.2001-04.com.example:storage.kube.sys1.xyz-lun-0 type ext4 (rw,relatime,data=ordered)
/dev/mapper/mpathb on /var/lib/kubelet/pods/f527ca5b-6d87-11e5-aa7e-080027ff6387/volumes/kubernetes.io~iscsi/iscsipd-rw type ext4 (rw,relatime,data=ordered)

两段输出揭示了一条重要事实:每个 Portal 的 LUN 都会先在 kubelet 的插件目录(/var/lib/kubelet/plugins/kubernetes.io/iscsi/<portal>-<iqn>-lun-<n>)挂载一次,再被 bind-mount 到 Pod 的卷目录(/var/lib/kubelet/pods/<pod-uid>/volumes/kubernetes.io~iscsi/...),最终进入容器的挂载点。这正是 kubelet 的 iSCSI 卷插件在节点上的实际落盘形态。

3. 用 docker 命令复核容器内挂载

如果 ssh 到该节点,可以用 docker ps 查看实际运行的容器:

# docker ps
CONTAINER ID        IMAGE                                  COMMAND             CREATED             STATUS              PORTS               NAMES
3b8a772515d2        kubernetes/pause                       "/pause"            6 minutes ago       Up 6 minutes                            k8s_iscsipd-rw.ed58ec4e_iscsipd_default_f527ca5b-6d87-11e5-aa7e-080027ff6387_d25592c5

再通过 docker inspect 确认容器把宿主机目录挂载到了容器内的 /mnt/iscsipd:

# docker inspect --format '{{ range .Mounts }}{{ if eq .Destination "/mnt/iscsipd" }}{{ .Source }}{{ end }}{{ end }}' f855336407f4
/var/lib/kubelet/pods/f527ca5b-6d87-11e5-aa7e-080027ff6387/volumes/kubernetes.io~iscsi/iscsipd-ro

# docker inspect --format '{{ range .Mounts }}{{ if eq .Destination "/mnt/iscsipd" }}{{ .Source }}{{ end }}{{ end }}' 3b8a772515d2
/var/lib/kubelet/pods/f527ca5b-6d87-11e5-aa7e-080027ff6387/volumes/kubernetes.io~iscsi/iscsipd-rw

这里用 Go 模板 {{ range .Mounts }} 遍历容器的所有挂载,筛选出 Destination 为 /mnt/iscsipd 的条目并打印其 Source,即宿主机上对应的卷目录——它与 kubelet 的 pod 卷路径完全一致,从而闭环验证「iSCSI 设备 → 宿主机卷目录 → 容器挂载点」的完整链路。

仓库证据:示例清单的自动化校验

本仓库通过 examples_test.go 对全部示例清单做了 schema 级校验,iSCSI 相关文件也在覆盖范围内:

  • 在 TestExampleObjectSchemas 的用例表中,目录 ../examples/volumes/iscsi 下的三个文件分别按预期类型解码并校验:chap-secret → api.Secret、iscsi → api.Pod、iscsi-chap → api.Pod(见 examples_test.go),即仓库中的 chap-secret.yaml、iscsi.yaml、iscsi-chap.yaml 均能通过 Kubernetes 自身的对象校验器。
  • 更进一步的 TestReadme 还会解析 README 中的 YAML 代码块,将其解码并校验;其中 iSCSI README 被显式列入测试路径,期望类型为 api.Secret(见 examples_test.go),这意味着文档内嵌的 CHAP Secret 示例本身也是可解码、可校验的有效 Kubernetes 对象。

这从侧面印证了本文所有配置片段的语法与字段均符合 Kubernetes API 规范,可以直接作为部署蓝本使用。

小结

Kubernetes 内置的 iSCSI 卷插件让集群可以直接消费外部 SAN/iSCSI 存储,而无需在节点上手工维护挂载脚本。回顾本指南的关键要点:

  1. 最小配置只需 targetPortal、iqn、lun、fsType 四个字段,多路径场景再补充 portals,非 TCP 传输补充 iscsiInterface;
  2. 设备分区有约束:插件不支持分区,请使用单分区或裸盘,让 Kubernetes 在首次挂载时自动格式化;
  3. CHAP 认证通过 chapAuthDiscovery、chapAuthSession 与 secretRef 组合启用,凭据必须以 kubernetes.io/iscsi-chap 类型的 Secret 提供,并严格使用与 Open-iSCSI 对应的 8 个键;
  4. 验证路径清晰可循:kubectl get pods 看运行状态,节点 mount | grep kub 看设备与目录映射,docker inspect 确认容器内挂载点来源。

以仓库中 iscsi.yaml 与 iscsi-chap.yaml 为起点,替换为你自己的 Portal、IQN 与认证凭据,即可快速搭建起一套可复用的 iSCSI 持久化存储接入方案。

登录后查看全文
examples