文档中心

容器服务

存储组件

csi-ebs

csi-ebs 组件为基于标准 CSI 接口规范实现的弹性块存储（云盘）驱动组件。本文介绍如何安装和升级 csi-ebs 组件以及相关的注意事项。

组件概述

csi-ebs 是容器服务提供的核心存储插件，主要用于在集群中集成和管理云盘（EBS）资源。它负责桥接集群与底层的存储服务，当您的业务需要持久化保存数据时，该组件会自动帮您申请云盘、格式化并挂载到指定的 Pod 中，保障数据在 Pod 重启或迁移时不丢失。

该组件为非托管组件，需要在您的业务集群节点上运行，会占用少量的节点计算资源。组件安装后，会在 kube-system 命名空间中自动拉起以下 Kubernetes 资源。

资源名称	资源类型	资源说明
csi-ebs-controller	Deployment	云盘管理 Pod，负责监听集群内的存储需求（PVC/PV），并调用云端 API 自动化完成云盘的创建、扩容、删除以及挂载/卸载调度。
csi-ebs-node	DaemonSet	云盘挂载 Pod，运行在集群的每一个计算节点上，负责在节点本地执行云盘的格式化，并最终将其挂载到 Pod 所在的容器目录中。

说明

上表中仅罗列出了该组件的主要资源，以及配置组件或对应功能时可能使用到的资源，方便您了解该组件的主要组成。其他的组件相关资源（例如 ConfigMap、Secret 等）不多做介绍，请以集群中的实际为准。

组件版本

关于组件的历史发布记录、各版本新增特性及优化说明等信息，详情请参见组件发布记录。

安装组件

登录容器服务控制台。

在左侧导航栏中，选择集群，单击目标集群名称，进入集群管理页面。

在左侧导航栏中，选择组件管理，并选择存储页签。

将鼠标移动到组件卡片上，单击部署，配置组件相关参数。

参数	描述
部署方式	组件的部署方式。当前该参数已固定，不可配置。
部署形态	仅已安装了 vci-virtual-kubelet 组件的集群显示该参数。部署组件的节点类型，有如下两种方式：云服务器部署：表示在集群中的云服务器节点（Node）上部署该组件。弹性容器部署：部署于弹性容器 VCI 实例上，将使用 1 个 2 vCPU、4 GiB 规格的 VCI 实例，且会产生额外的费用。详细的费用说明，请参见弹性容器实例产品计费。
项目	选择组件所属项目。默认选择 default（默认项目）。更多项目相关操作和说明，请参见项目管理。
节点保留盘数量	配置集群维度的 EBS 保留盘数量。用于实现系统资源预留能力，避免磁盘资源被完全消耗。当该配置为空时：若节点规格允许挂载的 EBS 磁盘数量 ≥ 16 个，则系统默认预留 4 个磁盘作为保留盘。若节点规格允许挂载的 EBS 磁盘数量 < 16 个，则系统会预留 30% 磁盘作为保留盘。例如：若节点规格最多允许挂 15 块云盘，则容器服务最多允许挂载 14*（1-0.3）= 10 块云盘。当该配置有具体的值时，系统会根据配置预留盘。例如：若节点规格最多允许挂 16 块云盘，同时该参数配置为 1，则此时容器服务最多允许挂载 15 块云盘。注意修改节点保留盘数量后，系统会自动重启 csi-ebs 组件，以保证修改后的数据生效。为避免影响在线业务，建议在业务低峰期进行。
节点保留盘数量同步周期	同步节点标签ebs.csi.volcengine.com/reserve-volumes以更新节点保留盘数量的周期，空值表示禁用该功能。
开启云盘在线变配	开启后，允许通过 VolumeAttributesClass 资源在线修改云盘规格、Burst 和额外性能。更多操作和说明，请参见变更云盘类型。
开启已分配盘数量指标	开启后 controller 将暴露已分配盘数量的指标，分配给 VCI 实例的盘不会统计。在某些异常场景下，这个指标的值可能不准确，推荐使用 kube-state-metrics 提供的kube_volumeattachment_info指标。
节点监控采集端口	节点监控数据采集端口，默认为 11815。推荐配置为 12000 以内的端口。
节点健康检查端口	节点健康检查端口，默认为 9808。推荐配置为 12000 以内的端口。
节点标签选择	仅部署形态选择云服务器部署时，可配置该参数。开启后，可设置节点标签，组件的核心工作负载会被调度到带有该指定标签的节点上。
节点污点调度	仅部署形态选择云服务器部署时，可配置该参数。开启后，可设置污点容忍值，组件的核心工作负载允许被调度到带有指定污点的节点。
节点联通中心后启动	启用后，节点 csi-ebs-node 在启动时将持续探测 API Server，等待网络可用后继续启动。可降低启动时发生异常的可能性。
资源配置	自定义组件内各资源的 CPU 请求和上限、内存请求和上限。

单击确认，完成配置。

升级组件

已知问题

建议您及时升级组件版本，若您仍在使用当前组件的低版本，可能存在以下问题。

问题现象	问题原因	影响版本	修复版本
存储卷的访问模式为 ReadWriteMany 时挂载失败。	属于错误用法。由于云盘不支持同时挂载到多个节点，组件早期版本未对访问模式进行强制校验。	>= v1.1.0	错误用法，暂不修复
专有宿主机 DDH 机型上的 csi-ebs-node 启动失败，组件状态异常。	DescribeInstanceTypes 接口的请求参数使用 InstanceTypeIds，但专有宿主机 DDH 机型并未支持该参数。	< v1.2.9	v1.2.9
节点可分配给负载的云盘数量不准确。	csi-ebs-node 启动期间访问 Metadata Server 或 OpenAPI 失败，节点最大可用云盘数量为默认值 16。	< v1.2.6	v1.2.6
csi-ebs-node 未向 kubelet 注册，Pod 处于 ContainerCreating 状态。	卸载旧版本组件之前，已经拉起新版本 Pod，导致向 kubelet 注册在取消注册之前。	< v1.1.8	v1.1.8
访问 Metadata Server 超时导致 zone 为空字符串，CSI node/controller 无法正常工作。	未校验 zone 是否为空字符串。	< v1.1.7	v1.1.7
存储类未指定 projectName 但云盘已经存在的场景，检查 projectName 失败。	存储类未指定 projectName 时，创建的云盘默认 Project 为 default。	v1.1.5	v1.1.6
存在三代机型的集群安装组件失败。	组件默认挂载了 scsi 设备，但三代机型没有该设备。	< v1.1.2	v1.1.2

升级风险

组件升级过程或组件升级失败时，不会影响存量业务。组件升级过程中，将重建组件相关工作负载，会导致正在处理且未完成的操作受到影响，表现为资源状态无法就绪。组件升级成功后，未完成的操作会自动重试，等待资源状态就绪即可，无需人为干预。

组件升级过程中可能受到影响的操作如下：

创建存储卷声明（动态卷）：由于创建卷未成功导致存储卷声明未绑定。

删除存储卷声明（动态卷）：由于删除卷未成功，导致存储卷声明处于Terminating状态。

创建工作负载：由于挂载卷未成功导致工作负载处于ContainerCreating状态。

删除工作负载：由于卸载卷未成功导致工作负载处于Terminating状态。

说明

若业务对存储卷声明的绑定时间和工作负载的启动成功率要求较高，需要进一步评估影响，建议在业务低峰期升级组件。

升级步骤

前往目标集群的组件管理页面，将鼠标移动到组件卡片上，单击 ... 中的升级，一键升级到最新版本。更多详细说明参见：升级组件。

注意

若升级失败，可根据报错提示修复故障后重新升级。

若升级过程遇到问题或期望升级到指定版本，可联系官方售前或提交工单获取技术支持。

检查组件状态

组件安装/升级完成后，您可以通过控制台或 kubectl 命令行，确认组件工作是否正常。

通过控制台验证

通过 kubectl 命令行验证

登录容器服务控制台。

在左侧导航栏中，选择集群，单击目标集群名称，进入集群管理页面。

在左侧导航栏中，选择工作负载 > 无状态负载，检查kube-system命名空间中的无状态负载csi-ebs-controller是否处于就绪状态，若所有 Pod 均处于就绪状态，则代表升级成功。

在左侧导航栏选择工作负载 > 守护进程，检查kube-system命名空间中的守护进程csi-ebs-node是否处于就绪状态，若所有 Pod 均处于就绪状态，则代表升级成功。

观测与告警

组件观测

csi-ebs 组件稳定性和性能直接影响组件功能正常使用和效果，建议您在集群中开启组件观测，帮助您实时掌握组件的健康度。详情请参见 CSI 存储观测。

开启组件观测后，您可以在控制台中查看组件预置观测看板。该该看板主要展示 csi-ebs 组件运行状态和云盘卷操作链路，包括 Controller Pod 可用状态、Node Pod 可用状态、控制面操作积压、控制面 RPC 调用失败、节点 RPC 调用失败、云存储 OpenAPI 调用失败、云存储 OpenAPI 延迟和节点 RPC 延迟等。支持设置查询的时间段，并指定刷新方式（手动刷新、自动刷新）。

在集群管理页面的左侧导航栏中，选择监控中心 > 监控看板。

在左侧看板列表中选择存储服务监控 > EBS 监控，即可查看监控看板。

配置告警

容器服务基于托管 Prometheus（VMP）提供完善的集群监控告警能力，您可以直接使用系统预置模板快速创建告警规则组，也可以基于业务实际需求自定义基于 PromQL 语句的告警规则，或在导出预置模板 YAML 后调整规则并沉淀为自定义告警模板，统一复用于多个集群。详情请参见：

使用预置模板配置告警

使用自定义模板配置告警

自定义告警规则

预置告警模板由系统根据常见运维场景预置，适合首次建设告警体系或快速补充基础监控项，帮助您及时发现组件资源不足或运行异常。预置告警模板告警规则详情，请参见预置告警模板。