Docs

Volcengine Kubernetes Engine

Nodes

Add existing nodes

Worker nodes in a cluster can provide computing and storage resources for applications. You can add one or more nodes to a cluster by adding existing Elastic Compute Service (ECS) instances. This topic describes the detailed steps and parameter configuration for adding existing nodes.

Prerequisites

The target cluster is in the Running state.

You have available ECS instances in the same VPC as the cluster. For instructions, see Purchase Elastic Compute Service.

Considerations

The ECS instances that you selected will be rebound to security groups.

To ensure the ECS instances can be added successfully, make sure that you format their data volumes to clear all the data. Otherwise, these data volumes will fail to be mounted to the storage directories /var/lib/containerd and /var/lib/kubelet respectively for the containers and images, and ECS instances cannot be added successfully.

The bare metal or certain High Performance Computing Optimized GPU nodes will be shut down when they are added to a cluster. For more details, see StopInstance.

This topic describes the procedure of adding existing nodes to the default node pool vke-default-nodepool. Some custom node pools with certain restrictions also support adding existing nodes. For details, see Manage node pools.

Adding existing nodes to a cluster for the first time

If existing nodes are added to a cluster for the first time, a node pool needs to be configured to manage the nodes (ECS instances) to be added. The node pool name vke-default-nodepool is specified by VKE. After you add nodes, you can view them on the Node pool page. Other parameters for vke-default-nodepool need to be configured according to the instructions below.

tip

After vke-default-nodepool is created, it will serve as the default node pool for the cluster. Any existing nodes added to this cluster in the future will be managed in the vke-default-nodepool node pool.

The default node pool does not consume your node pool quota. For details about quota, see Limit.

In the left navigation bar, select Cluster.

In the cluster list, click the name of the target cluster to which you want to add nodes.

In the left navigation bar, select Nodes > Node.

On the Node page, click Add existing node.

Configure node parameters according to the following parameter descriptions.

Elastic Compute Service Choose

Parameter	Description
Target node project	The project to which the ECS instance to be added belongs. VKE will list the ECS instances in the selected project that can be added to the VKE cluster.
All servers	This list displays all ECS instances that are in the same VPC as the current cluster in the selected project. Select the ECS instances as needed.
Selected servers	This list displays the ECS instances that you have selected.
Keep ECS instance name	If this option is selected, the original name of the ECS instance will be retained after it is added to the cluster. tip If the names retained contain any Chinese characters, the system label cluster.vke.volcengine.com/node-name for that node will become invalid. Therefore, you need to avoid using the cluster.vke.volcengine.com/node-name label in scenarios such as affinity-based scheduling. If this option is unselected, the ECS instance will be renamed by VKE after it is added.
Disk mount	If you select this checkbox, the data volume will be formatted and mounted to /var/lib/containerd and /var/lib/kubelet. Device name: (Required) Specify the data volume device. You can enter the device name of the data volume, e.g., /dev/vdb, or the partition name of the data volume, e.g., /dev/vdb1. Mount point: Specify the mount point path. If the mount point is not specified, the default mount point will be used, such as /mnt/vdb. warning Before enabling it, make sure that the data volumes of the selected ECS instances to be added to the cluster do not have any residual data. Otherwise, adding existing nodes will fail. For actions to clear residual data from the data volume, see FAQ. If it is not enabled (default), the /var/lib/containerd and /var/lib/kubelet directories are mounted to the system volume partition where the operating system runs.
Reinstall OS	If you select this option, the operating system of the ECS instance will be reinstalled, and the existing data on the system volume of the instance will be cleared. If you do not select this option, the ECS instance will retain its existing operating system and system volume data. warning If you continue to use the existing operating system and system volume data of the ECS instance, make sure that the ECS instance meets the following requirements. Otherwise, the node will fail to be added. The ECS instance must be in the RUNNING state. The ECS instance must have the Cloud Assistant Agent installed, and the Cloud Assistant Agent must be in the Running state. Go to the ECS console to view the status of the ECS instance and its related resources.
Operating system	This parameter is displayed after you select Reinstall OS. Select an operating system image for nodes based on your business requirements. Valid values: Public images, Custom images, and Shared images. Public images: official, copyrighted images provided by Volcano Engine. These images combine basic OS with initialization components, delivering security, high availability, and open access for all users. For the public images supported by VKE and their associated instance families, see Overview of operating system images. Custom images: Images created and uploaded by you. In addition to the operating system, the images also have public or private applications pre-installed. These images are suitable for redeploying complex initialization systems or deploying multiple systems with the same configurations. VKE allows you to specify custom images as node operating systems. For more details, see Overview of operating system images. Shared images: the images shared by other Volcano Engine accounts. You can use shared images to quickly deploy the same software environment as that of nodes created by other users, or share custom images that you have created or uploaded with other Volcano Engine accounts. warning You need to create custom images and shared images by using VKE base images. Check whether a GPU version is required based on your business requirements. Custom images are available at the node pool project level.
Restart and install cloud assistant Agent	This parameter is displayed after you select Reinstall OS. The agent is installed by default. This setting cannot be modified. Using the Agent to manage nodes can facilitate fault monitoring and self-healing.
ECS tags	VKE will bind the Volcano Engine platform labels to the ECS instances added to the cluster to facilitate search and management. Click Add new, and enter the key and value as prompted on the page.

Security configuration

Parameter	Description
Security group	To ensure the proper functioning of clusters and nodes, VKE provides a security group by default. If you need to add custom security group rules, ensure the new rules do not conflict with the default ones. For more information about the default security group, see Security group settings.
Login methods	Configure the login method for nodes of the cluster running on VKE. Password: Enter the root password twice to confirm. SSH key pair: A secure login authentication method that consists of a public key and a private key and supports only Linux instances. If there are no SSH key pairs available, click Create key pair at the bottom of the Key pair dropdown menu to create one. For an introduction to key pairs, see Key pairs. tip The reason for configuring login methods here is that the operating systems on the ECS to be added will be reinstalled with the image you selected in the Operating system settings. Any ECS instances added afterward to the default node pool vke-default-nodepool will inherit this login method. You can change the login method by editing the default node pool.
Security reinforcement	Configure host security hardening. Enable (default): The host-based intrusion detection system (HIDS) provides free risk alerting services, such as alerts for abnormal logins. While maintaining compatibility with host operating system images, HIDS provides security hardening features for nodes (ECS instances), including real-time monitoring, file monitoring, process monitoring, and dynamic system analysis. Disable: The security hardening feature is not enabled.

More configuration

Parameter	Description
Node labels	Labels in VKE function identically to Kubernetes labels. Labels can be used to define attributes for nodes, facilitating node operations and management. A label can be added in batches to all the nodes in the node pool. Click Add node labels and enter a key and its value. warning Custom node labels cannot be the same as system labels. For details of system labels, see System labels and taints.
Node taints	Taints allow nodes to repel specific pods and therefore prevent those pods from being scheduled to the nodes. You can add the same taint to multiple nodes in the node pool at the same time. Click Add node taints, and enter the key and value as prompted on the page. warning Custom node taints cannot conflict with system taints. For a list of system taints, see System labels and taints.
Enable auto renew for node labels and taints	Configure automatic updating for node labels and taints. Selected (default): enables automatic updating. The labels or taints added to or modified in a node pool will be automatically synchronized to both the existing and new nodes. In addition, if you modify the labels or taints for existing nodes, the configurations of the nodes will be overwritten by the configurations of the node pool. Cleared: does not enable automatic updating. The labels or taints added to or modified in a node pool will be synchronized only to the new nodes, but not the existing ones. In addition, if you modify the labels and taints for existing nodes, the modified configurations take effect and will not be overwritten by the configurations of the node pool. warning Disabling automatic updating for node labels and taints may cause features that use fixed node labels to behave unexpectedly. Proceed with caution.
Node pool tags	Custom resource tags, which are used to flexibly manage the default node pool vke-default-nodepool. Click Add new, and enter the key and value based on the on-screen prompts.

Advanced settings

Parameter	Description
Custom name	Select and configure the custom name types for nodes in the node pool as needed. You can configure multiple custom name types at the same time. tip VKE provides a tool for automatically specifying custom names for all nodes in a node pool. To use the tool, click Auto generation. After custom names are automatically configured, we recommend that you click Generate random names to add random suffixes to prevent the custom names of the newly scaled-out nodes from conflicting with each other. This ensures smooth scale-out of nodes in the node pool. Nodes added during subsequent scale-out operations in the node pool will use the custom name set here or be named according to the custom naming rule set here. Node name: used to quickly identify nodes in VKE or ECS. You can use one of the following methods to specify node names: Node name prefix: Specify the node name prefix based on the displayed naming rules. Node metadata name: Specify the metadata name (metadata.name) of a node object in Kubernetes. The metadata name is used to identify resources in external systems such as monitoring and alerting systems. You can use one of the following two methods to specify metadata names: Use node hostname: Use the hostname of the node as the node metadata name. Set prefix and suffix for node metadata name: Specify the prefix or suffix of the node metadata name. The system generates the complete node metadata name in the prefix-node IP-suffix format.
Image lazy loading	[Public beta] This feature is not enabled by default. If it is enabled, the nodes in the node pool vke-default-nodepool can use the container image acceleration feature as needed. For more information, see Container image lazy loading solutions. warning Only nodes that run containerd 1.4.13-vke.3 or later can use this feature. To view containerd versions, see FAQ.
InitializeScript	Enter a shell script. After Kubernetes add-ons are deployed on the node, the script is automatically executed. You need to implement the script commands yourself and ensure that the script supports reentrancy and retry logic. The script and the related logs can be found in the /usr/local/vke/userscripts directory on the node. This feature is commonly used in scenarios such as modifying kubelet configurations.
Cordon node	Disabled by default. If enabled, new pods cannot be scheduled to that node. This action only applies to worker nodes. You can also execute the kubectl uncordon command to disable it manually.

Check the configurations and then click Confirm to start adding nodes.

On the Node page, view the status of the node you just added. The status showing Running indicates that the node was added successfully.

Adding more existing nodes to a cluster

At this point, the default node pool vke-default-nodepool already exists. You can continue to add existing nodes according to the following instructions.

In the left navigation bar, select Cluster.

In the cluster list, click the name of the target cluster to which you want to add nodes.

In the left navigation bar, select Nodes > Node.

On the Node page, click Add existing node.

Configure node parameters according to the following parameter descriptions.

Default node pool information

Parameter	Description
Node pool management	Displays the default node pool name and configuration information. The existing nodes added to the cluster will inherit all configurations of the default node pool. This parameter cannot be updated.

Elastic Compute Service Configuration

Parameter	Description
Target node project	The project to which the ECS instance to be added belongs. VKE will list the ECS instances in the selected project that can be added to the VKE cluster.
All servers	This list displays all ECS instances under your account in the current region that are in the same VPC as the current cluster. Select the ECS instances as needed.
Selected servers	This list displays the ECS instances that you have selected.
Keep ECS instance name	If this option is selected, the original name of the ECS instance will be retained after it is added to the cluster. tip If the names retained contain any Chinese characters, the system label cluster.vke.volcengine.com/node-name for that node will become invalid. Therefore, you need to avoid using the cluster.vke.volcengine.com/node-name label in scenarios such as affinity-based scheduling. If this option is unselected, the ECS instance will be renamed by VKE after it is added.
Disk mount	If you select this checkbox, the data volume will be formatted and mounted to /var/lib/containerd and /var/lib/kubelet. You also need to set the Device name parameter to specify a device name. You can enter the device name of the data volume, e.g., /dev/vdb, or the partition name of the data volume, e.g., /dev/vdb1. warning Before enabling it, make sure that the data volumes of the selected ECS instances to be added to the cluster do not have any residual data. Otherwise, adding existing nodes will fail. For actions to clear residual data from the data volume, see FAQ. If it is not enabled (default), the /var/lib/containerd and /var/lib/kubelet directories are mounted to the system volume partition where the operating system runs.
Reinstall OS	If you select this option, the operating system of the ECS instance will be reinstalled, and the existing data on the system volume of the instance will be cleared. If you do not select this option, the ECS instance will retain its existing operating system and system volume data. warning If you continue to use the existing operating system and system volume data of the ECS instance, make sure that the ECS instance meets the following requirements. Otherwise, the node will fail to be added. The ECS instance must be in the RUNNING state. The ECS instance must have the Cloud Assistant Agent installed, and the Cloud Assistant Agent must be in the Running state. Go to the ECS console to view the status of the ECS instance and its related resources.
Operating system	This parameter is displayed after you select Reinstall OS. Select an operating system image for nodes based on your business requirements. Valid values: Public images, Custom images, and Shared images. Public images: official, copyrighted images provided by Volcano Engine. These images combine basic OS with initialization components, delivering security, high availability, and open access for all users. For the public images supported by VKE and their associated instance families, see Overview of operating system images. Custom images: Images created and uploaded by you. In addition to the operating system, the images also have public or private applications pre-installed. These images are suitable for redeploying complex initialization systems or deploying multiple systems with the same configurations. VKE allows you to specify custom images as node operating systems. For more details, see Overview of operating system images. Shared images: the images shared by other Volcano Engine accounts. You can use shared images to quickly deploy the same software environment as that of nodes created by other users, or share custom images that you have created or uploaded with other Volcano Engine accounts. warning You need to create custom images and shared images by using VKE base images. Check whether a GPU version is required based on your business requirements. Custom images are available at the node pool project level.
Restart and install cloud assistant Agent	This parameter is displayed after you select Reinstall OS. The agent is installed by default. This setting cannot be modified. Using the Agent to manage nodes can facilitate fault monitoring and self-healing.

More configuration

Parameter	Description
Node labels	Labels in VKE function identically to Kubernetes labels. Labels can be used to define attributes for nodes, facilitating node operations and management. A label can be added in batches to all the nodes in the node pool. Click Add node labels and enter a key and its value. warning Custom node labels cannot be the same as system labels. For details of system labels, see System labels and taints.
Node taints	Taints can prevent specific pods from being scheduled to this node. You can add the same taint to multiple nodes in a node pool in batch. Click Add node taints, and enter the key and value as prompted on the page. warning Custom node taints cannot conflict with system taints. For a list of system taints, see System labels and taints.

Advanced settings

Parameter	Description
Image lazy loading	[Public beta] This feature is not enabled by default. If it is enabled, the nodes in the node pool vke-default-nodepool can use the container image acceleration feature as needed. warning Only the nodes with a containerd version 1.4.13-vke.3 or later can use this feature. To view containerd versions, see FAQ.
InitializeScript	Enter a shell script. After Kubernetes add-ons are deployed on the node, the script is automatically executed. You need to implement the script commands yourself and ensure that the script supports reentrancy and retry logic. The script and the related logs can be found in the /usr/local/vke/userscripts directory on the node. This feature is commonly used in scenarios such as modifying Containerd configuration parameters.
Cordon node	Disabled by default. If enabled, new pods cannot be scheduled to that node. This action only applies to worker nodes. You can also execute the kubectl uncordon command to disable it manually.

Check the configurations and then click Confirm to start adding nodes.

On the Node page, view the status of the node you just added. The status showing Running indicates that the node was added successfully.

Last updated: 2026.09.20 15:59:33