《Kubernetes 分布式系统原理深入解析》7.1 CSI 规范:Controller/Node 插件与 gRPC

第 6 章的 StorageClass 只是入口,真正造卷的是 CSI 规范。本节拆解 CSI 的 Controller 与 Node 两个插件角色、gRPC 接口契约,以及外部 provisioner/attach-detacher 如何把 K8s 对象翻译成 CSI 调用。lab 用 csi 包验证 CreateVolume/DeleteVolume 的完整卷生命周期。

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)面向数据面:把卷挂进节点/PodNodeStageVolume、NodePublishVolume

lab 里 NewController 持有 Volumes 与 Attached 映射,NewNode 持有 Mounted 映射——这正是在拓扑上分家的最小模型:Controller 知道「卷存在于哪、被谁 attach」,Node 知道「卷挂到了本机哪个路径」。 一个卷的生命周期被劈成两半,一半归控制面协调,一半归节点执行。

gRPC 接口契约:三大服务

CSI 定义三大 gRPC 服务,每个服务一组方法:

服务关键方法语义
IdentityGetPluginInfo、GetCapabilities插件是谁、支持什么能力
ControllerCreateVolume、DeleteVolume、ControllerPublishVolume、ControllerUnpublishVolume卷的供应与 attach 协调
NodeNodeStageVolume、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,背后是存储接口的特殊性:

维度gRPCREST/JSON
契约proto 强类型,编译期校验松散,靠文档约束
流式天然支持双向流需自行实现
幂等键请求字段显式携带依赖 HTTP 语义
性能二进制编码文本编码,开销大

存储接口要的是「强契约 + 长调用」:CreateVolume 可能持续几十秒,需要明确的超时、重试与幂等键;这些在 gRPC 里是结构化的请求字段,而不是散落的口头约定。接口协议本身也是架构决策——选 gRPC,等于把「契约清晰」作为插件生态的头等要求。

外部组件:provisioner 与 attach-detacher

K8s 不与 CSI 插件直接互调,中间隔着一层「外部组件」(sidecar),它们是 CSI 规范配套的翻译官:

sidecar翻译方向触发对象
csi-provisionerPVC → CreateVolume → 回写 PVStorageClass 里点名 provisioner 的 PVC
csi-attacherVolumeAttachment → ControllerPublishVolume/UnpublishPod 调度产生的 attach 请求
csi-snapshotterVolumeSnapshot → CreateSnapshot快照 CRD 对象

一条动态供给链路的完整时序是:

  1. PVC 声明 storageClassName: fast,fast 的 provisioner 是 ebs.csi.aws.com。
  2. csi-provisioner 监听到 PVC,调用 Controller 的 CreateVolume(id, size)。
  3. 云厂商造出一块卷,provisioner 生成对应 PV,K8s 完成绑定(6.1 节)。
  4. Pod 调度到节点,csi-attacher 调用 ControllerPublishVolume 把卷 attach 到节点。
  5. 节点上的 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 CreateVolumeController.CreateVolume
attachController ControllerPublishVolumeController.Attach
挂载Node NodePublishVolumeNode.Publish
卸载Node NodeUnpublishVolumeNode.Unpublish
detachController ControllerUnpublishVolumeController.Detach
删卷Controller DeleteVolumeController.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 与挂载;不再使用,才允许删除。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图