Docs

Volcengine Kubernetes Engine

Terraform

Managing existing nodes in a custom node pool by using Terraform

This topic describes how to add nodes to or remove nodes from a custom node pool by using Terraform.

Prerequisites

A cluster has been created by using Terraform. For details, see Managing clusters created with Terraform.

A node pool has been created by using Terraform. For details, see Creating custom node pools.

There are ECS instances that can be added. For details, see Purchasing ECS instances.

Limit

When you add an existing ECS instance to a custom node pool:

The custom node pool must meet the following requirements:

The autoscaler is not enabled for the node pool.

The current node pool status is running.

The current node pool billing mode is Pay-as-you-go or Subscription.

For ECS instances, the following conditions need to be met:

Running in the same VPC as the current cluster.

Be under the same project as the target node pool.

The instance is not in a scaling group of any cluster or autoscaler service.

The instance only has one network interface card.

The system volume of the instance has a capacity ≥ (image size configured for the target node pool + 10 GiB).

The data volumes of the instance must include the data volumes specified for mounting in the target node pool, and the volume type and size must be exactly the same.

Adding existing nodes to a custom node pool

Follow the steps below to add an ECS instance to a custom node pool by using Terraform.

Create a folder and a configuration file named main.tf in the folder.

terraform {
required_providers {
volcengine = {
source = "volcengine/volcengine"
version = "0.0.140" # Query available versions from the official Terraform website (https://registry.terraform.io/providers/volcengine/volcengine/latest).
}
}
}
provider "volcengine" {
access_key = "**********" # The access key ID of the Volcano Engine root user.
secret_key = "**********" # The secret access key of the Volcano Engine root user.
region = "cn-beijing" # The region where the VKE cluster is located.
}
data "volcengine_vke_clusters" "default" {
name_regex = "tf-created-vke" # The name of the cluster to which the node pool created by Terraform belongs.
}
resource "volcengine_vke_node_pool" "node-pool-test" {
cluster_id = data.volcengine_vke_clusters.default.clusters[0].id
name = "demo" # The name of the custom node pool.
instance_ids = ["i-ydazicr0n4yg********"] # The ID of the existing node (ECS instance).
keep_instance_name = true # Whether to retain the original ECS instance name. The value false indicates no retention and the value true indicates retention.
node_config {
instance_type_ids = ["ecs.c1ie.large"] # The specification of the ECS instance.
subnet_ids = ["subnet-rrmacgc4b37kv******"] # The ID of the subnet ID to which the node network belongs.
security {
login {
password = "*******" # The access credential of the node. It is the password of the root user. The value must be Base64-encoded.
}
}
# The system volume. The type must be supported for mounting.
system_volume {
type = "ESSD_PL0" # The cloud disk type. Valid values include ESSD_PL0 (PL0 ESSD) and ESSD_FlexPL (PL1 ESSD).
size = 40 # Cloud disk capacity in GiB. The value range for ESSD (ESSD_PL0 and ESSD_FlexPL) is 40 to 2048.
}
# If this setting is enabled and configured, the first data volume will be mounted to /mnt/vdb, and to the /var/lib/containerd and /var/lib/kubelet directories.
# If a custom mount point is set, the data volume will be mounted to the custom mount point, and to the /var/lib/containerd and /var/lib/kubelet directories.
additional_container_storage_enabled = true
# Data volumes. The type must be mountable by the selected node and must support a custom mount point.
data_volumes {
type = "ESSD_PL0" # Disk type. Valid values include ESSD_PL0 (PL0 ESSD) and ESSD_FlexPL (PL1 ESSD).
size = 50 # Disk capacity in GiB. The value range for ESSD (ESSD_PL0 and ESSD_FlexPL) is 40 to 2048.
}
data_volumes {
type = "ESSD_PL0"
size = 50
}
ecs_tags { # Labels associated with the ECS instance as the node. The labels are used for filtering and managing ECS instances.
key = "ecs_k1"
value = "ecs_v1"
}
}
kubernetes_config {
# Configure node labels.
labels {
key = "aaa"
value ="bbb"
}
cordon = false # Whether to cordon the node. The value true indicates cordoning and false indicates no cordoning.
}
tags { # Custom labels for the node pool.
key = "k1"
value = "v1"
}
}

Initialize the Terraform environment.

terraform init

The expected result is as follows.

Initializing the backend...

Initializing provider plugins...
- Finding volcengine/volcengine versions matching "0.0.140"...
- Installing volcengine/volcengine v0.0.140...

...

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Perform resource planning.

terraform plan

The expected result is as follows.

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
~ update in-place

Terraform will perform the following actions:
...
Plan: 0 to add, 1 to change, 0 to destroy.

Add the existing instance to the custom node pool.

terraform apply

The expected result is as follows.

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
~ update in-place

Terraform will perform the following actions:
...
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.

Enter a value: yes

volcengine_vke_node.node-pool-test: Updating...
...
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

You can also view nodes in the custom node pool (with the ID pcq3p3f****** in this example) in the VKE console.

Removing a node from a custom node pool

To remove a previously added node from a custom node pool using Terraform, follow these steps.

Warning

Regardless of whether the billing method for the existing node to be removed is subscription or pay-as-you-go, this action will not release the node. You can release the node in the ECS console. For detailed steps, see Deleting instances.

This action is only intended to remove existing nodes (ECS instances) that were previously added to the custom node pool. To remove nodes created in the custom node pool, update the replica quantity of the custom node pool. For details, see Node pool scaling.

In the main.tf file, go to the volcengine_vke_node_pool section and remove the ID of the target ECS instance from the instance_ids field value.

...
resource "volcengine_vke_node_pool" "node-pool-test" {
cluster_id = data.volcengine_vke_clusters.default.clusters[0].id
name = "demo"
instance_ids = ["i-ydazicr0n4yg********"] # Remove the ID of the ECS instance to be deleted from the value of this field (including the double quotation marks).
...
}

Run the command to remove the node.

terraform apply

The expected result is as follows.

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
~ update in-place
Terraform will perform the following actions:
...
Plan: 0 to add, 1 to change, 0 to destroy.
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value: yes
...
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

You can check whether the node has been removed from the target custom node pool in the VKE console.

Last updated: 2026.03.31 10:58:15