Kubernetes iSCSI 持久化卷接入实战:基于 open-iscsi 与 multipathd 的 Pod 存储配置指南
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 主机上通过软件方式搭建,官方文档给出了三条参考路径:
- 在 Fedora 上搭建 iSCSI Target(配置 target 侧导出 LUN);
- 在 Fedora 上安装并配置 iSCSI initiator(节点侧发起连接);
- 若需要 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 存储,而无需在节点上手工维护挂载脚本。回顾本指南的关键要点:
- 最小配置只需
targetPortal、iqn、lun、fsType四个字段,多路径场景再补充portals,非 TCP 传输补充iscsiInterface; - 设备分区有约束:插件不支持分区,请使用单分区或裸盘,让 Kubernetes 在首次挂载时自动格式化;
- CHAP 认证通过
chapAuthDiscovery、chapAuthSession与secretRef组合启用,凭据必须以kubernetes.io/iscsi-chap类型的 Secret 提供,并严格使用与 Open-iSCSI 对应的 8 个键; - 验证路径清晰可循:
kubectl get pods看运行状态,节点mount | grep kub看设备与目录映射,docker inspect确认容器内挂载点来源。
以仓库中 iscsi.yaml 与 iscsi-chap.yaml 为起点,替换为你自己的 Portal、IQN 与认证凭据,即可快速搭建起一套可复用的 iSCSI 持久化存储接入方案。