文档中心

容器服务

节点管理

CreateNodes - 添加已有节点

在指定集群下添加已有的云服务器（ECS）实例。

使用说明

调用该接口前，请确保已创建节点池（默认节点池或自定义节点池）且节点池状态必须处于 {Running, [*]}或{Scaling,[Progressing]}状态，否则无法调用该接口添加已有节点。

默认节点池：调用 CreateDefaultNodePool 接口创建默认节点池（vke-default-nodepool），或者通过控制台在添加已有节点时创建默认节点池。

自定义节点池：调用 CreateNodePool 接口创建自定义节点池，或者通过控制台创建节点池。

注意

仅满足如下条件的自定义节点池，支持添加 ECS 实例：

节点池未开启弹性伸缩开关。

当前节点池计费模式为按量计费或包年包月。

仅满足如下条件的 ECS 实例，支持被添加到自定义节点池：

属于当前集群相同的私有网络（VPC）。

与目标节点池所属的项目（Project）一致。

实例未加入任何集群或弹性伸缩（Auto Scaling）服务的伸缩组。

实例仅有一张网卡，已绑定多张网卡的 ECS 实例不支持被添加。

实例系统盘需满足：容量 ≥ （目标节点池配置的镜像大小+ 10 GiB）。

如果不自定义配置节点要挂载的数据盘（即 AdditionalContainerStorageEnabled 参数的值不为 true），则实例数据盘必须包含目标节点池指定了挂载的数据盘，且盘类型和大小完全一致。例如目标节点池配置了 5 块数据盘（含本地盘），其中第一块数据盘开启了“格式化并挂载到容器、镜像存储目录”，第三块数据盘开启了“指定挂载目录”，则该 ECS 实例必须包含与节点池第一块和第三块数据盘的类型、大小完全相同的数据盘（含本地盘）。

调用该接口前，请先调用 ListSupportedResourceTypes 接口，确认创建节点时需要用到的资源是否在指定的地域和可用区中支持。

此接口为异步接口，当此接口返回成功时，会返回节点的 ID 信息，此时节点将进入{Creating, [Progressing]}状态，直到创建执行成功{Running, [Ok]}。请调用 ListNodes 接口获取该节点当前的状态，查看节点是否创建成功。

添加弹性裸金属型节点后，下线此类节点时，ECS 侧会根据运行状态优先正常关机，如无法正常关机，将执行强制关机。更多信息，请参见 StopInstance。

请求说明

VKE 已在全球多个地域部署服务，旨在为您提供更稳定、低延迟的访问体验。您可以通过查阅服务地址文档，根据业务所在地域，选择最合适的接入点。

请求方式：POST

请求地址：https://vke.cn-beijing.volcengineapi.com?Action=CreateNodes&Version=2022-05-12

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

调用该 API 时的请求参数如下，除此之外还需传入公共请求参数。公共请求参数说明，请参见公共参数。

参数	类型	是否必选	示例值	描述
Action	String	是	CreateNodes	接口名称。当前 API 的名称为 CreateNodes。
Version	String	是	2022-05-12	接口版本。当前 API 的版本为 2022-05-12。
ClientToken	String	否	ed6b1190-dc17-11ec-9519-eb58a7******	用于保证请求幂等性的字符串。该字符串由调用方传入，需保证不同请求之间唯一。ClientToken 对大小写敏感，且最大值不超过 64 个 ASCII 字符。
ClusterId	String	是	cc5sil******	集群的 ID。可以调用 ListClusters 接口，获取集群 ID。注意集群必须处于{Running,[*]} 或 {Updating,[Progressing]}状态。可调用 ListClusters 接口获取集群当前的状态。
NodePoolId	String	否	pjklj******	节点池 ID。不传入参数值：表示将已有 ECS 实例添加到默认节点池。传入参数值：表示将已有 ECS 实例添加到自定义节点池。可调用 ListNodePools 接口，获取目标自定义节点池 ID。注意若此处填写自定义节点池 ID，则待添加的节点将应用自定义节点池上的 Kubernetes 配置和节点配置（包括 ECS 实例标签、标签、污点、封锁节点配置、项目、节点名称前缀等），因此 InitializeScript、KubernetesConfig、ImageId 参数配置将无效，上述参数仅在默认节点池中添加已有节点时有效。
InstanceIds	Array of String	是	["i-ybo9229pdf**","i-ybo9229pdf**"]	要添加到集群的 ECS 实例 ID。单次调用最多支持填写 100 个 ECS 实例 ID。调用 DescribeInstances 接口，获取 ECS 实例 ID。该 ECS 实例须满足以下条件：与集群在同一个私有网络内。未被其他集群使用。实例状态必须处于运行中（Running）。添加的节点数量不能超过集群所支持的最大节点数上限。请勿重复添加同一个 ECS 实例。注意若将 ECS 实例添加到自定义节点池，请注意以下事项：当前节点池启用了 AffinityGroupConfig 亲和组配置（邀测）时，此处填写的 ECS 实例 ID 数量必须是亲和组规格的整数倍，否则无法成功添加。当前节点池未启用 AffinityGroupConfig（邀测）时，若您填写了亲和组 ECS 实例 ID，可能会导致非预期行为。建议在非亲和组购买方式的节点池中，不要选择亲和组 ECS 实例。
KeepInstanceName	Boolean	否	false	是否保留原 ECS 实例名称，取值： false：（默认值）不保留原 ECS 实例名称，由容器服务自动为其命名。 true：保留原 ECS 实例名称。
AdditionalContainerStorageEnabled	Boolean	否	false	选择配置节点的数据盘并格式化挂载作为容器镜像和日志的存储目录，取值： false：（默认值）关闭。默认节点池：表示不挂载数据盘。自定义节点池：使用节点池的数据盘配置进行挂载，被添加到节点池的 ECS 实例数据盘必须包含目标节点池指定了挂载的数据盘（含本地盘），且盘类型和大小完全一致。 true: 开启。此时必须同时配置 ContainerStoragePath 参数。节点通过 ContainerStoragePath参数中的配置进行挂载，而忽略节点池的数据盘配置，对被添加到节点池的 ECS 实例数据盘无特殊要求。
ContainerStoragePath	String	否	/dev/vdb	使用该数据盘设备挂载容器和镜像存储目录/var/lib/containerd。仅当AdditionalContainerStorageEnabled=true时有效，且不能为空。须满足以下条件，否则将初始化失败：仅支持已挂载数据盘的 ECS 实例。指定数据盘设备名时，请确保该数据盘设备存在，否则会初始化失败。指定数据盘分区或逻辑卷名时，请确保该分区或逻辑卷存在，且为 ext4 文件系统。注意指定数据盘设备时，将自动格式化后直接挂载，请注意提前备份数据。指定数据盘分区或逻辑卷名时，不需要格式化。
ImageId	String	否	image-k*******	节点对应的 ECS 实例使用的镜像 ID。不同的镜像类型对应的镜像 ID 也不同，详细说明，请参见容器服务支持的公共镜像。注意若不传该参数，优先分配 veLinux 2.0 系列的镜像 ID。
InitializeScript	String	否	ZWNo******	创建 ECS 节点并完成 Kubernetes 组件部署后执行的脚本。输入Base64 编码后的 Shell 格式脚本。为空时，节点继承使用默认节点池配置的初始化脚本NodeConfig.InitializeScript。自定义填写脚本内容后，使用自定义的脚本，忽略默认节点池配置的初始化脚本。说明 Base64 编码后长度不超过 8 KB。若同时传入 InitializeScript 和 PreScript，则两个参数的传入值总长度也不能超过 8 KB。
KubernetesConfig	Object of KubernetesConfigRequest	否	-	节点 Kubernetes 相关配置。为空时，节点继承使用默认节点池的 Kubernetes 配置KubernetesConfig.Labels/Taints/Cordon。自定义填写配置后，使用自定义配置内容，忽略默认节点池的 Kubernetes 配置。
SkipReplaceSystem	Boolean	否	true	添加已有节点时是否跳过重置系统： true：跳过重置系统，即不重置已有节点对应 ECS 实例的操作系统。 false：（默认值）不跳过重置系统，即重置已有节点对应 ECS 实例的操作系统。注意若需要跳过重置系统（取值为true），请确保： ECS 实例状态必须为 RUNNING，可调用 DescribeInstances 查询实例状态。 ECS 实例必须安装云助手 Agent 且状态为 Running，可调用 DescribeCloudAssistantStatus 查询云助手 Agent 状态。
PreScript	String	否	ZWNoby******	【邀测·申请试用】部署节点前执行的脚本。输入Base64 编码后的 Shell 格式脚本。说明参数值为空时，待添加的节点继承默认节点池配置的前置脚本 NodeConfigRequest.PreScript。自定义填写脚本内容后，将会忽略默认节点池配置的前置脚本，使用此处输入的脚本。 Base64 编码后长度不超过 8 KB。若同时传入 InitializeScript 和 PreScript，则两个参数的传入值总长度也不能超过 8 KB。
GpuDriverVersion	String	否	550.127.05	【该参数已废弃，请使用 GpuDriverConfig 代替】指定在节点上安装的 GPU 驱动版本。可以调用 ListSupportedGpuDriverVersions 接口，获取镜像支持安装的 GPU 驱动版本列表。
GpuDriverConfig	Object of GpuDriverConfig	否	-	节点 GPU 驱动配置。该配置的优先级高于GpuDriverVersion字段。说明该参数适用于默认节点池和自定义节点池。添加到自定义节点池且未配置该参数时，节点继承使用自定义节点池的GpuDriverConfig配置。
ContainerStorageMountPoint	String	否	/mnt/vdb	数据盘设备格式化后的目标挂载目录，配合ContainerStoragePath使用，不填时挂载到默认目录。仅当AdditionalContainerStorageEnabled=true时有效。

KubernetesConfigRequest

参数	类型	是否必选	示例值	描述
Cordon	Boolean	否	false	封锁节点配置，取值： false：（默认值）不封锁 true：封锁说明更新节点池（UpdateNodePoolConfig）时，若不传入参数值，则保持原有参数配置。
Labels	Array of Label	否	-	节点池/节点的 Kubernetes 标签（Labels）信息。最多可传入 20 个标签。说明节点池会统一管理节点的标签配置信息，因此标签信息会同步到节点池内的所有节点上。当标签发生变更时，会覆盖原有的标签配置信息。
Taints	Array of Taint	否	-	节点池/节点的 Kubernetes 污点（Taints）信息。最多可传入 20 个污点。说明节点池会统一管理节点的污点配置信息，因此污点信息会同步到节点池内的所有节点上。当污点发生变更时，会覆盖原有的污点配置信息。

Label

参数	类型	是否必选	示例值	描述
Key	String	是	label-key	标签键，要求如下，更多规则，请参见 Kubernetes 标签规则。有效的标签键有两个段：<前缀>和<名称>，用斜杠（/）分隔。 <名称>是必须的，支持英文大小写字母、数字、短划线（-）、下划线（_）、英文句号（ .），以字母或数字开头和结尾，长度不超过 63 个字符。 <前缀>是可选的。如果指定<前缀>，则必须是 DNS 子域：由英文句号（.）分隔的一系列 DNS 标签，长度不超过 253 个字符。 <前缀>和<名称>总长度不超过 82 个字符。
Value	String	否	label-value	标签值，要求如下，更多规则，请参见 Kubernetes 标签规则。长度不超过 63 个字符（可以为空）。支持以英文大小写字母、数字开头和结尾。支持特殊字符：短划线（-）、下划线（_）、英文句号（.）。

Taint

参数	类型	是否必选	示例值	描述
Key	String	是	taint-key	污点键，要求如下，更多规则，请参见 Kubernetes 标签规则。有效的污点键有两个段：前缀和名称，用斜杠（/）分隔。名称是必须的，支持英文大小写字母、数字、特殊字符- _ .，以字母或数字开头和结尾，长度不超过 63 个字符。前缀是可选的。如果指定前缀，则必须是 DNS 子域：特殊字符.分隔的一系列 DNS 标签，长度不超过 253 个字符。前缀和名称总长度不超过 82 个字符。
Value	String	否	taint-value	污点值，要求如下，更多规则，请参见 Kubernetes 标签规则。长度不超过 63 个字符（可以为空）。支持以英文大小写字母、数字开头和结尾。支持特殊字符：- _ .
Effect	String	否	NoSchedule	污点效果，取值： NoSchedule：（默认值）不调度。 NoExecute：驱逐没有容忍污点的 Pod。 PreferNoSchedule：尽量避免调度。

GpuDriverConfig

参数	类型	是否必选	示例值	描述
GpuDriverVersion	String	否	580.105.08	指定节点安装的 GPU 驱动版本号。可以调用 ListSupportedGpuDriverVersions 接口，获取镜像支持安装的 GPU 驱动版本列表。当配置为空时，系统会按照 GPU 机型自动填充推荐的 GPU 驱动版本。
InstallGpuDriver	Boolean	否	true	当 ECS 实例为 GPU 机型，且使用公共基础镜像（例如 veLinux 1.0、Ubuntu 22.04）时，是否自动安装 GPU 驱动。取值： true：自动安装 GPU 驱动。配置为该参数时，您可以使用GpuDriverVersion参数指定具体的 GPU 驱动。 false：不自动安装 GPU 驱动。说明当 ECS 实例为 GPU 机型时，该配置默认为 true。当 ECS 实例为非 GPU 机型时，该配置不生效。

请求示例

返回参数

本接口返回参数如下表所示，公共返回参数请参见返回结果。

参数	类型	示例值	描述
Ids	Array of String	["nc5t5epmrsf****"]	节点 ID 列表。

返回示例

错误码

本接口错误码如下表所示，公共错误码请参见公共错误码。

HTTP 状态码	错误码	错误信息	说明
400	QuotaExceeded.Node	The number of nodes in the cluster has reached the limit.	您当前集群所要创建的节点数量超出系统限额。您可以选择其他地域，也可以提交工单申请提高配额。
400	OperationDenied.ClusterStatus	The action is forbidden due to cluster status {{statusPhase}} and {{statusConditions}}.	指定集群的当前状态不支持该操作。请确认该接口依赖的集群状态后重试。
400	OperationDenied.NodePoolStatus	The action is forbidden on node pool {{nodePoolId}} due to node pool status {{statusPhase}} and {{statusConditions}}.	指定节点池的当前状态不支持该操作。请确认该接口依赖的节点池状态后重试。
400	ClusterVpcMismatch.{{parameter}}	The specified {{resourceType}} {{resourceId}} is not in the VPC of cluster.	指定的子网、安全组、高性能计算集群与集群属于不同私有网络，请确保其与集群处于同一个私有网络内。
400	LimitExceeded.NodeInCluster	The number of nodes exceeds the cluster defined pods config limit.	Flannel 容器网络类型下，节点池设置的期望节点数超出了集群支持的最大节点数。容器服务各资源限制，请参见使用限制。支持的最大节点数取决于 PodsConfig.FlannelConfig.PodCidrs 和 MaxPodsPerNode。集群创建完成后不支持修改，请合理规划集群设置。
400	AlreadyInUse.{{parameter}}	The specified {{resourceType}} {{resourceId}} has already been used in another cluster.	指定的 ECS 实例已加入其他集群，请更换其他实例，或者从其他集群中移除该实例后重试。
400	OperationDenied.InstanceStatus	The operation has been denied due to the wrong status of the specified ECS instance {{instanceId}}.	ECS 实例当前状态不支持该操作。请确认调用该接口时的云服务器实例状态要求后重试。
400	ZoneMismatch.Instance	The specified ECS instance {{instanceId}} is not in the cluster defined zones.	vpc-cni集群下，添加的instance所在可用区不在集群所选pod子网对应的可用区范围内。
400	NotSupported.{{parameter}}	The specified {{resourceType}} {{resourceContent}} is not supported.	指定参数不支持，如 InstanceType、ImageId 等。请确认参数后重试。
400	ClusterVersionMismatch.ImageId	The specified ImageId {{imageId}} and KubernetesVersion {{kubernetesVersion}} are mismatched.	指定的镜像 ID（ImageId）与集群 Kubernetes 版本不匹配。请根据参数说明，配置准确的参数值后重试。
400	ImageIdMismatch.InstanceId	The specified InstanceId {{instanceId}} and ImageId {{imageId}} are mismatched.	指定的 ECS 实例 ID（InstanceIds）与镜像 ID（ImageId）不匹配。请根据参数说明，配置准确的参数值后重试。
400	OperationDenied.NodePoolReplicas	The operation has been denied due to the node pool min/max replicas limit.	添加节点超过了节点池最大节点数上限。请减少要添加的云服务器实例 ID 数量后重试。若目标节点池已开启弹性伸缩功能，可更新目标节点池最大节点数上限（MaxReplicas）后，重新调用本接口添加已有节点。调用 UpdateNodePoolConfig 接口更新节点池。
400	AlreadyInScalingGroup.{{parameter}}	The specified InstanceId {{instanceId}} has already been used in another scaling group.	指定的实例已被其他伸缩组使用，无法添加到节点池。
400	NodePoolConfigMismatch.InstanceId	The specified InstanceId {{instanceId}} and nodePool Config {{content}} are mismatched.	指定的 ECS 实例（InstanceIds）与目标节点池（NodePoolId）的配置不匹配。包括节点池对应的系统盘、数据盘、节点池所属项目等。请确认待添加的 ECS 实例与目标节点池的配置信息后重试。
400	OperationDenied.NodePoolAutoScalingEnabled	The operation has been denied because nodePool AutoScaling is enabled.	目标节点池已开启弹性伸缩功能，不支持添加已有 ECS 实例到该节点池。请关闭节点池的弹性伸缩功能或更换节点池后重试。
400	OperationDenied.InstanceEniNumber	The operation has been denied because the InstanceId {{instanceId}} has more than one eni.	指定的 ECS 实例有一张以上网卡（即有辅助网卡），因此不支持添加该实例到节点池。请解绑节点池的辅助网卡或更换 ECS 实例后重试。
400	ImageSizeMismatch.SystemVolumeSize	The specified system volume size and image size are mismatched.	指定的系统盘大小和镜像大小不匹配，系统盘需要比镜像大 10 GiB 以上。请根据参数说明，配置准确的参数值后重试。
404	NotFound.DefaultNodePool	The default node pool is not found.	默认节点池不存在，请先在控制台创建默认节点池。创建默认节点池的方法，请参见添加已有节点。
409	AlreadyExists.{{parameter}}	The specified {{resourceType}} {{resourceId}} already exists.	指定的云服务器实例已加入默认节点池。
400	AffinityGroupMismatch.InstanceIds	The specified InstanceIds and AffinityGroup {{AffinityGroupId}} are mismatched.	指定的 ECS 实例与亲和组不匹配。亲和组节点池中的节点数量必须是亲和组规格整数倍。请查看您指定的节点池和节点并确认相关参数说明后重试。
400	OperationDenied.CloudAssistantStatus	The operation has been denied due to the cloud assistant wrong status of the specified ECS instance {{instanceId}}.	ECS 实例的云助手 Agent 不在期望的状态，无法加入到集群中。请确认参数后重试。
400	LimitExceeded.ScriptLength	The InitializeScript and PreScript total length exceeds maximum allowed length.	前置脚本与后置脚本总长度超出限制。请根据参数说明，配置准确的参数值后重试。

最近更新时间：2026.09.15 14:34:51

这个页面对您有帮助吗？

有用

无用