Docs

Volcengine Kubernetes Engine

Terraform

Managing clusters created by Terraform

This topic describes how to create clusters using Terraform and manage such clusters.

Preparations

Before managing VKE clusters with Terraform, follow the steps below to install Terraform.

Download and install the desired version from the official Terraform website. For details, see Terraform documentation.

Warning

Ensure that the Terraform version is not lower than v0.13. You can run the terraform version command to query the version.

Configure Volcano Engine account information in Terraform.

Create environment variables to store authentication credentials.

export VOLCENGINE_ACCESS_KEY="AK************"
export VOLCENGINE_SECRET_KEY="************"
export VOLCENGINE_REGION="cn-beijing"

The following table describes the parameters.

Parameters	Description
VOLCENGINE_ACCESS_KEY	The AK of your Volcano Engine root user. For the method of obtaining it, see Access key.
VOLCENGINE_SECRET_KEY	The SK of your Volcano Engine root user. For the method of obtaining it, see Access key.
VOLCENGINE_REGION	The region where the VKE cluster is located. For the regions supported by VKE, see Regions and availability zones.

Specify the provider section of the configuration file.

provider "volcengine" {
access_key = "AK************"
secret_key = "************"
session_token = "sts token"
region = "cn-beijing"
}

The following table describes the parameters.

Parameters	Description
access_key	The AK of your Volcano Engine root user. For instructions on obtaining the SK, see Access key.
secret_key	The SK of your Volcano Engine root user. For instructions on obtaining the SK, see Access key.
session_token	(Optional) The security token for role assumption, which can be obtained by calling the AssumeRole API.
region	The region where the VKE cluster is located. Specify the same value as the value of the VOLCENGINE_REGION parameter configured in the previous step.

Creating clusters

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.
}

# Create a VPC.
resource "volcengine_vpc" "vke-tf-vpc" {
vpc_name = "vke-tf-vpc" # The name of the VPC.
cidr_block = "172.16.0.0/16" # VPC subnet CIDR block.
}

# Create a Virtual Switch (VSW).
resource "volcengine_subnet" "vke-tf-vsw" {
subnet_name = "vke-tf-vsw-1" # VSW subnet name.
cidr_block = "172.16.0.0/24" # VSW subnet CIDR block.
zone_id = "cn-beijing-a" # VSW availability zone.
vpc_id = volcengine_vpc.vke-tf-vpc.id # The ID of the VPC to which the VSW belongs.
}

# Create a VKE cluster.
resource "volcengine_vke_cluster" "vke-tf-test" {
name = "tf-created-vke" # Cluster name.
kubernetes_version = "1.24" # The Kubernetes version of the cluster. Currently, only the x.y version form is supported. The x.y.z version form is not supported.
# For Kubernetes versions supported by VKE, visit https://www.volcengine.com/docs/6460/108841.
description = "vke created by tf" # Cluster description.
delete_protection_enabled = true # Cluster deletion protection. The value true enables the feature. The value false disables the feature.
cluster_config {
subnet_ids = [volcengine_subnet.vke-tf-vsw.id] # Cluster subnet ID.
api_server_public_access_enabled = true # Whether to enable public access to API Server. The value true enables the feature. The value false disables the feature.
# Configure the billing mode and bandwidth for the EIP of API Server.
api_server_public_access_config {
public_access_network_config {
billing_type = "PostPaidByTraffic" # EIP billing mode. PostPaidByTraffic indicates Pay-as-you-go - Billing by actual traffic. PostPaidByBandwidth indicates Pay-as-you-go - Billing by bandwidth cap.
bandwidth = 10 # EIP bandwidth peak. For the PostPaidByTraffic billing mode, the value range is 1 to 200. For the PostPaidByBandwidth billing mode, the value range is 1 to 500.
}
}
resource_public_access_default_enabled = true # Enable public access. The value true enables the feature. The value false disables the feature.
}
pods_config {
pod_network_mode = "VpcCniShared" # Container network model. VpcCniShared indicates the VPC-CNI network model. Flannel indicates the Flannel network model.
# When the network model is Flannel, flannel_config takes effect.
flannel_config {
pod_cidrs = ["192.168.0.0/20"] # Pod CIDR for Flannel pod networking.
max_pods_per_node = 64 # Maximum number of pod instances per node for Flannel pod networking. Valid values are 64, 16, 32, 128, and 256.
}
# When the network model is VpcCniShared, vpc_cni_config takes effect.
vpc_cni_config {
subnet_ids = [volcengine_subnet.vke-tf-vsw.id] # The ID of the pod subnet in VPC-CNI pod networking.
}
}
# Configure the cluster service CIDR.
services_config {
service_cidrsv4 = ["192.168.16.0/24"] # CIDR used by services within the cluster.
}
}

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:
+ create

Terraform will perform the following actions:

...

Plan: 3 to add, 0 to change, 0 to destroy.

Create a cluster.

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:
+ create

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_vpc.vke-tf-vpc: Creating...
...
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

You can log in to the VKE console to view the created cluster.

Updating clusters

Follow the steps below to use Terraform to update a cluster created by Terraform.

Update the main.tf file and set the delete_protection_enabled field to false to disable cluster deletion protection.

...
description = "vke created by tf"
delete_protection_enabled = false
cluster_config {
...

Update cluster configurations.

tip

Because the field for updating the cluster configuration is not a ForceNew field, resources will not be deleted and recreated.

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.

Deleting clusters

Follow the steps below to use Terraform to delete a cluster created by Terraform.

Warning

If you delete a cluster by using Terraform, all cluster-associated resources except subscription worker nodes will be automatically released. Exercise caution when you perform this operation.

Update the main.tf file and set the delete_protection_enabled field to false to disable cluster deletion protection.

...
description = "vke created by tf"
delete_protection_enabled = false
cluster_config {
...

Delete the target cluster and associated resources, such as CLB resources used by the cluster API Server.

terraform destroy

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 really want to destroy all resources?
Terraform will destroy all your managed infrastructure, as shown above.
There is no undo. Only 'yes' will be accepted to confirm.

Enter a value: yes
...
Destroy complete! Resources: 3 destroyed.

Last updated: 2026.07.23 14:31:47