7.1 CSI 规范:Controller/Node 插件与 gRPC
6.1 节让 StorageClass 点名 ebs.csi.aws.com,但没回答「csi.aws.com 到底是什么」。答案是:一个符合 CSI(Container Storage Interface) 规范的插件进程。CSI 是 K8s 与存储后端之间的行业标准接口——它把「造卷」「挂卷」「快照」等能力定义成一套固定的 gRPC 方法,让每个存储厂商实现自己的插件,而 K8s 不必为每家厂商改源码。
本节拆解 CSI 的两个插件角色与 gRPC 契约,再说明外部 provisioner 如何在 K8s 对象与 CSI 调用之间当翻译官。
为什么需要 CSI:把插件移出核心代码
CSI 之前的时代,存储插件分两类,各有痛点:
| 插件形态 | 痛点 |
|---|---|
| in-tree 插件(k8s 源码内置) | 每个云厂商都改 K8s 源码,合并周期以月计,且共享 kubelet 崩溃风险 |
| 独立 FlexVolume 脚本 | 只能传参数,无法做多步骤状态机,能力表达受限 |
CSI 用「进程外插件 + 标准协议」同时解决两者:插件是独立二进制,跑自己的生命周期;协议固定为 gRPC,能力通过 GetCapabilities 动态声明。K8s 只认接口,不认实现——接口稳定,实现才能自由迭代。
Controller 与 Node 插件:控制面与数据面的分家
CSI 把插件拆成两个角色,正好对应第 6.3 节讲的控制面/数据面分离:
| 插件 | 跑在哪里 | 职责 | 代表方法 |
|---|---|---|---|
| Controller 插件 | 集群内(Deployment) | 面向控制面:造卷、删卷、attach/detach、快照 | CreateVolume、ControllerPublishVolume |
| Node 插件 | 每个节点(DaemonSet) | 面向数据面:把卷挂进节点/Pod | NodeStageVolume、NodePublishVolume |
lab 里 NewController 持有 Volumes 与 Attached 映射,NewNode 持有 Mounted 映射——这正是在拓扑上分家的最小模型:Controller 知道「卷存在于哪、被谁 attach」,Node 知道「卷挂到了本机哪个路径」。 一个卷的生命周期被劈成两半,一半归控制面协调,一半归节点执行。
gRPC 接口契约:三大服务
CSI 定义三大 gRPC 服务,每个服务一组方法:
| 服务 | 关键方法 | 语义 |
|---|---|---|
| Identity | GetPluginInfo、GetCapabilities | 插件是谁、支持什么能力 |
| Controller | CreateVolume、DeleteVolume、ControllerPublishVolume、ControllerUnpublishVolume | 卷的供应与 attach 协调 |
| Node | NodeStageVolume、NodePublishVolume、NodeUnstageVolume、NodeUnpublishVolume | 卷在本节点的挂载与卸载 |
lab 用 Go 方法模拟这份契约,方法与 gRPC 一一对应:Controller.CreateVolume(id, size) 对应 Controller 服务的 CreateVolume,Controller.Attach(volID, nodeID) 对应 ControllerPublishVolume,Node.Publish(volID, path) 对应 NodePublishVolume。接口契约是这份规范的核心资产——后端只要实现这些方法,K8s 就能驱动它。
gRPC 契约长什么样
gRPC 契约用 proto 文件定义,下面是一段示意(截取 Controller 服务最核心的签名):
service Controller {
rpc CreateVolume(CreateVolumeRequest) returns (CreateVolumeResponse);
rpc DeleteVolume(DeleteVolumeRequest) returns (DeleteVolumeResponse);
rpc ControllerPublishVolume(ControllerPublishVolumeRequest)
returns (ControllerPublishVolumeResponse);
rpc ControllerUnpublishVolume(ControllerUnpublishVolumeRequest)
returns (ControllerUnpublishVolumeResponse);
}
message CreateVolumeRequest {
string name = 1; // PV 名,幂等键
int64 capacity_bytes = 2; // 容量
VolumeCapabilities volume_capabilities = 3; // 访问模式等
map<string, string> parameters = 4; // StorageClass 参数
}
name 是幂等键这一点值得强调:provisioner 重试 CreateVolume 时带同一个名字,后端必须返回同一个卷而不是再造一块——幂等是 CSI 可靠性的地基,第 7.2 节会看到它贯穿 attach/detach 的重试。
为什么是 gRPC:接口协议的取舍
CSI 选 gRPC 而不是 REST/JSON,背后是存储接口的特殊性:
| 维度 | gRPC | REST/JSON |
|---|---|---|
| 契约 | proto 强类型,编译期校验 | 松散,靠文档约束 |
| 流式 | 天然支持双向流 | 需自行实现 |
| 幂等键 | 请求字段显式携带 | 依赖 HTTP 语义 |
| 性能 | 二进制编码 | 文本编码,开销大 |
存储接口要的是「强契约 + 长调用」:CreateVolume 可能持续几十秒,需要明确的超时、重试与幂等键;这些在 gRPC 里是结构化的请求字段,而不是散落的口头约定。接口协议本身也是架构决策——选 gRPC,等于把「契约清晰」作为插件生态的头等要求。
外部组件:provisioner 与 attach-detacher
K8s 不与 CSI 插件直接互调,中间隔着一层「外部组件」(sidecar),它们是 CSI 规范配套的翻译官:
| sidecar | 翻译方向 | 触发对象 |
|---|---|---|
| csi-provisioner | PVC → CreateVolume → 回写 PV | StorageClass 里点名 provisioner 的 PVC |
| csi-attacher | VolumeAttachment → ControllerPublishVolume/Unpublish | Pod 调度产生的 attach 请求 |
| csi-snapshotter | VolumeSnapshot → CreateSnapshot | 快照 CRD 对象 |
一条动态供给链路的完整时序是:
- PVC 声明
storageClassName: fast,fast的 provisioner 是ebs.csi.aws.com。 - csi-provisioner 监听到 PVC,调用 Controller 的
CreateVolume(id, size)。 - 云厂商造出一块卷,provisioner 生成对应 PV,K8s 完成绑定(6.1 节)。
- Pod 调度到节点,csi-attacher 调用
ControllerPublishVolume把卷 attach 到节点。 - 节点上的 Node 插件执行
NodeStageVolume/NodePublishVolume,卷出现在容器路径。
sidecar 的存在让 K8s 核心代码保持纯净:K8s 只管对象,sidecar 管翻译,CSI 插件管实现。 这也是 lab 把 CreateVolume/DeleteVolume/Attach/Detach 全部收进 Controller 一个类型的原因——它们本就属于同一个控制面契约。
sidecar 的部署形态
sidecar 与插件按角色组合部署,形态清晰可查:
| 部署 | 包含 | 运行方式 |
|---|---|---|
| Controller 侧 | csi-provisioner + csi-attacher + csi-snapshotter + Controller 插件 | 一个 Deployment,多容器同 Pod |
| Node 侧 | csi-node-driver-registrar + Node 插件 | 一个 DaemonSet,每个节点一个 |
Controller 侧的多个 sidecar 与插件容器「同 Pod 同生命周期」,共享一个本地 socket 互调——插件的 gRPC 服务端只对本 Pod 内可见,不对外暴露,这是安全边界也是部署惯例。Node 侧的 registrar 负责把插件的 socket 注册到 kubelet 的插件目录,让 kubelet 知道本机有哪些 CSI 能力。
卷生命周期走一遍:从 Create 到 Delete
把 6.2 节的生命周期套到 CSI 上,每一个状态都对应一个 gRPC 调用:
| 生命周期事件 | CSI 调用 | lab 对应 |
|---|---|---|
| 造卷 | Controller CreateVolume | Controller.CreateVolume |
| attach | Controller ControllerPublishVolume | Controller.Attach |
| 挂载 | Node NodePublishVolume | Node.Publish |
| 卸载 | Node NodeUnpublishVolume | Node.Unpublish |
| detach | Controller ControllerUnpublishVolume | Controller.Detach |
| 删卷 | Controller DeleteVolume | Controller.DeleteVolume |
DeleteVolume 的守卫条件(仅当未 attach、未挂载时允许)不是 lab 发明,而是 CSI 规范的硬要求:卷还在被使用时就删除,会留下悬空句柄与数据损坏。 状态机保证每个动作都发生在正确的阶段,这是「卷不丢不串」的协议级保障。
能力协商:GetCapabilities 决定可用功能
不是所有后端都支持所有能力。CSI 用 GetCapabilities 做能力协商,K8s/sidecar 据此决定可用功能:
| 能力位 | 含义 | 后端例子 |
|---|---|---|
CreateVolume | 支持动态供给 | 云盘后端必须支持 |
ControllerPublishVolume | 支持 attach/detach | 块后端支持,纯文件后端可不实现 |
CreateSnapshot | 支持快照 | 存储阵列能力,非必须 |
EXPAND_VOLUME | 支持在线扩容 | 云盘普遍支持,本地卷受限 |
lab 的 Controller 是「全能力」的简化模型;真实后端通过能力位声明自己支持什么,K8s 才敢派什么任务。能力协商避免「调用才发现的失败」——后端没有快照能力,snapshotter 就该绕行而不是傻调。
三个常见误解
- 「CSI 插件装在 Pod 里,通过 Kubelet 直接调用插件二进制」——错误。K8s 不与插件二进制直连,外部 sidecar 把 K8s 对象翻译成 gRPC 调用,插件实现 gRPC 服务端。
- 「Controller 和 Node 插件是同一个进程的两份副本」——错误。二者是职责不同的两个组件:Controller 管控制面(造卷/attach),Node 管数据面(本机挂载),通常部署形态也完全不同(Deployment vs DaemonSet)。
- 「创建卷就一步 CreateVolume 完成,Pod 就能用」——错误。从 CreateVolume 到 Pod 里看到数据要经过 attach、stage、publish 至少三步;任何一步失败 Pod 就卡在 ContainerCreating。
一句话总结本节
CSI 用 Controller/Node 两个插件角色与一套 gRPC 契约,把存储后端统一成可插拔实现:Controller 管造卷、删卷与 attach 协调,Node 管本机挂载;外部 provisioner/attach-detacher 在 K8s 对象与 CSI 调用之间当翻译官。接口稳定、实现自由,是这套规范让存储生态长出生机的原因。
下一节深入 attach/detach 的分布式协调:单写者独占、detach 必须先行卸载,以及卷漂移与超时重试背后的状态机。
本节 lab
本节用 csi 包的一个测试验证完整的卷生命周期:
cd private/labs/k8s-net-lab
go test ./csi -run TestVolumeLifecycle -v
- 断言
CreateVolume后卷存在——1 个断言,对应「Controller 造卷」。 - 断言未 attach 的卷
DeleteVolume返回成功——1 个断言,对应「删卷守卫:未被使用才可删」。 - 断言删除后卷从
Volumes消失——1 个断言,对应「删除真正生效」。
共 3 个断言,跑完见 ok k8s-net-lab/csi。这条「造 → 删」的闭环是 CSI 生命周期的最小路径:先有卷,才能 attach 与挂载;不再使用,才允许删除。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。