API docs by Redocly

VKS API (1.0.0)

Download OpenAPI specification:Download

Authorization document available at https://docs.api.vngcloud.vn/#api-documentation

Cluster Controller

Get the list of clusters

Authorizations:
Authorization
query Parameters
id
string
Default: ""
Example: id=k8s-123

Search by cluster ID

name
string
Default: ""
Example: name=cluster-name

Search by cluster name

page
integer <int32> >= 0
Default: 0
Example: page=0

Page number

pageSize
integer <int32> >= 1
Default: 10
Example: pageSize=10

Page size

status
string
Default: ""
Example: status=ACTIVE

Search by status

version
string
Default: ""
Example: version=v1.19.0

Search by cluster version

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters',
  qs: {
    id: 'k8s-123',
    name: 'cluster-name',
    page: '0',
    pageSize: '10',
    status: 'ACTIVE',
    version: 'v1.19.0'
  },
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 150,
  • "page": 0,
  • "pageSize": 10
}

Create a cluster

Authorizations:
Authorization
query Parameters
autoRenewal
boolean
Default: true
Example: autoRenewal=true

Enable auto renew

poc
boolean
Default: false
Example: poc=true

Enable poc

Request Body schema: application/json

Create cluster body

name
required
string^[a-z0-9\-]{5,20}$

The name of the cluster. Only letters (a-z, 0-9, '-') are allowed. Your input data length must be between 5 and 20.

description
string^[a-zA-Z0-9-_. @]{0,255}$

Description of the cluster. Only letters (a-z, A-Z, 0-9, '@', '.' , '_' , '-' , ' '). Your input data length must be between 0 and 255.

releaseChannel
required
object
Default: "STABLE"
Enum: "RAPID" "STABLE"

Specifies release channel of Kubernetes that suits your demand between feature availability and stability. We provide 2 release channels: STABLE and RAPID.

version
required
string [ 1 .. 50 ] characters
Default: "v1.29.13-vks.1740045600"

Specifies the version you wish to use for your Cluster. You can view all available Kubernetes versions here. The default value is "v1.29.13-vks.1740045600"

enablePrivateCluster
required
boolean
Default: false

Enables the private cluster feature, creating a private endpoint on the cluster. The VKS public clusters refer to a type of Kubernetes cluster configuration where the Kubernetes API server endpoint is publicly accessible over the internet. In an VKS public cluster, the API server endpoint is not restricted to private access within a VPC (Virtual Private Cloud) and can be accessed over the public internet. The VKS private clusters are configured to have private access to the Kubernetes API server endpoint. This means that the API server endpoint is only accessible from within a specific Virtual Private Cloud (VPC) and is not exposed to the public internet. Private clusters provide enhanced security by restricting access to the Kubernetes API to resources within the VPC. At this time, the default value of this field is false and we only offer Public Cluster mode. The default value is "false".

networkType
required
string^CALICO|CILIUM_OVERLAY|CILIUM_NATIVE_ROUTING$...
Default: "CILIUM_OVERLAY"
Enum: "CALICO" "CILIUM_OVERLAY" "CILIUM_NATIVE_ROUTING"

The type of network for the cluster. The default value is CILIUM_OVERLAY. You can choose one in many options including CALICO, CILIUM_OVERLAY, CILIUM_NATIVE_ROUTING. If you choose CILIUM_NATIVE_ROUTING, you need to set the secondarySubnets and nodeNetmaskSize field. If you choose CALICO or CILIUM_OVERLAY, you need to set the cidr field.

vpcId
required
string [ 1 .. 50 ] characters

The VPC ID for the cluster. You need to create a VPC on vServer and enter the VPC's ID in this field. List all of your VPCs in here

subnetId
required
string [ 1 .. 50 ] characters

The subnet ID for the cluster. You need to create a Subnet on vServer and enter the Subnet's ID in this field. List all of your Subnets in here

cidr
string

Specifies the CIDR block for the cluster using CALICO or CILIUM_OVERLAY network. You can enter a private IP CIDR from the following options: 10.0.0.0 - 10.255.0.0, 172.16.0.0 - 172.24.0.0, or 192.168.0.0. The default value is "172.16.0.0/16".

enabledLoadBalancerPlugin
boolean
Default: true

Enables/ Disable the attachment of load balancers (both network and application) via Kubernetes YAML. The default value is "true".

enabledBlockStoreCsiPlugin
boolean
Default: true

Enable/ Disable Automatically deploys and manages the BlockStore Persistent Disk CSI Driver via Kubernetes YAML. The default value is "true".

enabledServiceEndpoint
boolean
Default: false

Enables the creation and use of private service endpoints within your cluster.

secondarySubnets
Array of strings <= 10 items

Specifies additional subnets to be useds in Cilium's VPC Native Routing mode (max 10). List all of your Secondary subnet in here

nodeNetmaskSize
integer <int32> [ 24 .. 26 ]
Default: 25

Specifies the node CIDR mask size used in Cilium's VPC Native Routing mode. The default value is 25. You can enter a number from the following options: 24, 25, 26.

object

Cluster auto-upgrade configuration

object

Fleet configuration for this cluster

required
object

List of node groups to create in the cluster

Responses

Request samples

Content type
application/json
{
  • "name": "demo-cluster",
  • "description": "Demo cluster for testing purposes",
  • "releaseChannel": "STABLE",
  • "version": "v1.29.13-vks.1740045600",
  • "enablePrivateCluster": false,
  • "networkType": "CALICO",
  • "vpcId": "net-bf21c762-9b6f-45dc-9f1c-ac09158f3b3b",
  • "subnetId": "sub-a3144389-b92c-453a-83b7-e165defe66d8",
  • "cidr": "10.0.0.0/16",
  • "enabledLoadBalancerPlugin": true,
  • "enabledBlockStoreCsiPlugin": true,
  • "enabledServiceEndpoint": false,
  • "secondarySubnets": [
    ],
  • "nodeNetmaskSize": 24,
  • "autoUpgradeConfig": {
    },
  • "fleetConfig": {
    },
  • "nodeGroups": {
    }
}

Response samples

Content type
application/json
{
  • "id": "k8s-2ff9b24c-a58c-497c-b526-79630b0d3c92",
  • "name": "dev-cluster",
  • "description": "Development environment cluster",
  • "status": "ACTIVE",
  • "releaseChannel": "STABLE",
  • "version": "1.29.1",
  • "numNodes": 5,
  • "enablePrivateCluster": true,
  • "createdAt": "2024-12-01T10:00:00.000Z",
  • "updatedAt": "2025-01-05T16:30:00.000Z"
}

Get the cluster by ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "k8s-2ff9b24c-a58c-497c-b526-79630b0d3c92",
  • "name": "dev-cluster",
  • "description": "Development environment cluster",
  • "status": "ACTIVE",
  • "releaseChannel": "STABLE",
  • "version": "1.29.1",
  • "numNodes": 5,
  • "enablePrivateCluster": true,
  • "createdAt": "2024-12-01T10:00:00.000Z",
  • "updatedAt": "2025-01-05T16:30:00.000Z",
  • "networkType": "CALICO",
  • "vpcId": "vpc-12345",
  • "subnetId": "subnet-67890",
  • "secondarySubnets": [
    ],
  • "cidr": "10.0.0.0/16",
  • "enabledLoadBalancerPlugin": true,
  • "enabledBlockStoreCsiPlugin": false,
  • "enabledServiceEndpoint": true,
  • "whitelistNodeCIDRs": [
    ],
  • "poc": false,
  • "autoRenewal": true,
  • "nodeNetmaskSize": 24,
  • "serviceEndpoint": {
    },
  • "location": "hn-vng",
  • "autoUpgradeConfig": {
    },
  • "fleet": {
    }
}

Update the cluster by cluster ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Request Body schema: application/json

Update node group body

version
required
string [ 1 .. 50 ] characters

Specifies the version you wish to use for your Cluster. You can view all available Kubernetes versions here

whitelistNodeCIDRs
required
Array of strings [ 1 .. 30 ] items

List of CIDRs allowed to access cluster nodes

enabledLoadBalancerPlugin
boolean
Default: true

Enables/ Disable the attachment of load balancers (both network and application) via Kubernetes YAML. The default value is "true".

enabledBlockStoreCsiPlugin
boolean
Default: true

Enable/ Disable Automatically deploys and manages the BlockStore Persistent Disk CSI Driver via Kubernetes YAML. The default value is "true".

Responses

Request samples

Content type
application/json
{
  • "version": "v1.29.1",
  • "whitelistNodeCIDRs": [
    ],
  • "enabledLoadBalancerPlugin": true,
  • "enabledBlockStoreCsiPlugin": true
}

Response samples

Content type
application/json
{
  • "id": "k8s-2ff9b24c-a58c-497c-b526-79630b0d3c92",
  • "name": "dev-cluster",
  • "description": "Development environment cluster",
  • "status": "ACTIVE",
  • "releaseChannel": "STABLE",
  • "version": "1.29.1",
  • "numNodes": 5,
  • "enablePrivateCluster": true,
  • "createdAt": "2024-12-01T10:00:00.000Z",
  • "updatedAt": "2025-01-05T16:30:00.000Z"
}

Delete the cluster by ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Responses

Request samples 

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "k8s-2ff9b24c-a58c-497c-b526-79630b0d3c92",
  • "name": "dev-cluster",
  • "description": "Development environment cluster",
  • "status": "ACTIVE",
  • "releaseChannel": "STABLE",
  • "version": "1.29.1",
  • "numNodes": 5,
  • "enablePrivateCluster": true,
  • "createdAt": "2024-12-01T10:00:00.000Z",
  • "updatedAt": "2025-01-05T16:30:00.000Z"
}

Configure auto-upgrade for the cluster by ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Request Body schema: application/json

Cluster auto upgrade config body

weekdays
required
string

Days of the week to perform auto upgrade, e.g. 'Mon,Wed,Fri'

time
required
string

Time of day to perform auto upgrade in 24h format HH:mm, e.g. '03:00'

Responses

Request samples

Content type
application/json
{
  • "weekdays": "Mon,Wed,Fri",
  • "time": "03:00"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete the auto-upgrade config by cluster ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Responses

Request samples 

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/auto-upgrade-config',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get the list of events in a cluster

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

query Parameters
action
string
Default: ""
Example: action=CreateServer

Even action name

page
integer <int32> >= 0
Default: 0
Example: page=0

Page number

pageSize
integer <int32> >= 1
Default: 10
Example: pageSize=10

Page size

type
string
Default: ""
Example: type=Normal

Event type

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/events',
  qs: {action: 'CreateServer', page: '0', pageSize: '10', type: 'Normal'},
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 150,
  • "page": 0,
  • "pageSize": 10
}

Get the Kubernetes config by cluster ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/kubeconfig',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "error": {
    }
}

Configure the fleet for the cluster by ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Request Body schema: application/json

Config fleet body

fleetType
required
object
Enum: "NEW" "EXISTING"

Type of the fleet

id
string

Fleet ID

name
string^[a-z0-9\-]{5,20}$

Fleet name (5-20 lowercase alphanumeric or hyphens)

enableNorthSouthTraffic
boolean

Enable North-South traffic routing

enableEastWestTraffic
boolean

Enable East-West traffic routing

Responses

Request samples

Content type
application/json
{
  • "fleetType": "NEW",
  • "id": "flt-123",
  • "name": "my-fleet-01",
  • "enableNorthSouthTraffic": true,
  • "enableEastWestTraffic": false
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Stop POC by cluster ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Responses

Request samples 

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/stop-poc',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "error": {
    }
}

Unregister the fleet config by cluster ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Responses

Request samples 

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/unregister-fleet',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get the list of upgrade insights by cluster ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=0

Page number

pageSize
integer <int32> >= 1
Default: 10
Example: pageSize=10

Page size

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/upgrade-insight',
  qs: {page: '0', pageSize: '10'},
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 150,
  • "page": 0,
  • "pageSize": 10
}

Cluster Version Controller

Get list of cluster versions

Authorizations:
Authorization

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/cluster-versions',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
[
  • {
    }
]

Node Group Controller

Get list node groups by cluster ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=0

Page number

pageSize
integer <int32> >= 1
Default: 10
Example: pageSize=10

Page size

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/node-groups',
  qs: {page: '0', pageSize: '10'},
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 150,
  • "page": 0,
  • "pageSize": 10
}

Create a new node group

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

Request Body schema: application/json

Node group body

name
required
string^[a-z0-9-]{5,15}$

The name of the node group. Only letters (a-z), numbers (0-9), and hyphens ('-') are allowed. The length of your input must be between 5 and 15 characters.

numNodes
required
integer <int32> >= 0
Default: 3

The number of nodes to create in this cluster's node group. The number of nodes are between 1 and 10 nodes. If auto_scale_config is set, num_nodes need to be greater than or equal to Minimum node, and less than or equal to Maximum node. If auto_scale_config is not set, num_nodes need to be greater than or equal to 0, and less than or equal to 10.

imageId
required
string [ 1 .. 50 ] characters [ 1 .. 50 ]

Specifies the image you want to use for your node group. You can obtain the Image ID from the VKS Portal or from this link and enter it in this field. List all of our Image ID in here

flavorId
required
string [ 1 .. 50 ] characters [ 1 .. 50 ]

Specifies the flavor you want to use for your node in the node group. You can obtain the Flavor ID from this link and enter it in this field. List all of our Flavor ID in here

diskSize
required
integer <int32> [ 20 .. 5000 ]

Specifies the data disk size for new nodes in this node group. Must be between 20 GB and 1000 GB. The default value is "100".

diskType
required
string [ 1 .. 50 ] characters [ 1 .. 50 ]

Specifies the type of data disk for new nodes in this node group. Currently, SSD disks and NVME disks are available. List all of our disktypes in here

enablePrivateNodes
required
boolean

You can choose the mode that you want your node group works. The VKS public node groups include worker nodes deployed in public subnets within a VPC. These worker nodes have public IP addresses and CAN communicate directly with the public internet. The private node groups configuration involves deploying worker nodes within subnets of a VPC, ensuring they cannot directly access the public internet. All outbound traffic from these nodes is routed exclusively through a NAT gateway service. The default value is "false"

enabledEncryptionVolume
boolean

Indicates whether volume encryption should be enabled for the node group. The default is false.

securityGroups
required
Array of strings [ 1 .. 50 ] items

Specifies the security group for your cluster. A security group acts as a virtual firewall, controlling inbound and outbound traffic for associated resources. You can find the Security Group ID on the vServer Portal and input it here.

sshKeyId
required
string [ 1 .. 50 ] characters [ 1 .. 50 ]

Specifies the SSH key for secure credentials to prove your identity when connecting to the server. You can import a key and get the SSH Key ID on the vServer Portal to input here. List all of your SSH Keys in here

object

Labels to be applied to the nodes in the node group. A maximum of 50 labels is allowed. Each label key must have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

Array of objects (NodeGroupTaintDto) <= 50 items

The Kubernetes taints to be applied to the nodes in the node group. Maximum 50 taints are allowed.

subnetId
string [ 1 .. 50 ] characters [ 1 .. 50 ]

Subnet ID to use for the Auto Scaling group that is created for your node group. List all of your Subnet in here

secondarySubnets
Array of strings <= 10 items

List of secondary subnets for the node group. Maximum 10 subnets are allowed. List all of your Secondary subnet in here

object (NodeGroupAutoScaleConfigDto)

Configuration for node group autoscaling

required
object

Upgrade configuration for node group

object (PlacementGroupConfigDto)

Placement group configuration for node group

Responses

Request samples

Content type
application/json
{
  • "name": "nodegroup-01",
  • "numNodes": 3,
  • "imageId": "img-db7784d2-4516-478e-939f-35a04ac50617",
  • "flavorId": "flavor-7a7a8610-34f5-11ee-be56-0242ac120002",
  • "diskSize": 100,
  • "diskType": "vtype-7a7a8610-34f5-11ee-be56-0242ac120002",
  • "enablePrivateNodes": true,
  • "enabledEncryptionVolume": true,
  • "securityGroups": [
    ],
  • "sshKeyId": "ssh-d4cf9811-5806-4289-ba15-54378663726b",
  • "labels": {
    },
  • "taints": [
    ],
  • "subnetId": "sub-3b7c5f10-e417-4847-bf84-08d03365c61f",
  • "secondarySubnets": [
    ],
  • "autoScaleConfig": {
    },
  • "upgradeConfig": {
    },
  • "placementGroupConfigDto": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ng-123",
  • "clusterId": "cluster-123",
  • "name": "my-node-group",
  • "status": "CREATING",
  • "numNodes": 3,
  • "imageId": "image-123",
  • "createdAt": "2023-10-01T12:00:00.000Z",
  • "updatedAt": "2023-10-01T12:00:00.000Z"
}

Get the node group details by ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

nodeGroupId
required
string

ID of the node group

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/node-groups/%7BnodeGroupId%7D',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "ng-123",
  • "clusterId": "cluster-123",
  • "name": "my-node-group",
  • "status": "CREATING",
  • "numNodes": 3,
  • "imageId": "image-123",
  • "createdAt": "2023-10-01T12:00:00.000Z",
  • "updatedAt": "2023-10-01T12:00:00.000Z",
  • "flavorId": "flavor-7a7a8610-34f5-11ee-be56-0242ac120002",
  • "diskSize": 0,
  • "diskType": "vtype-7a7a8610-34f5-11ee-be56-0242ac120002",
  • "enablePrivateNodes": true,
  • "sshKeyId": "ssh-d4cf9811-5806-4289-ba15-54378663726b",
  • "imageOS": "ubuntu",
  • "securityGroups": [
    ],
  • "autoScaleConfig": {
    },
  • "upgradeConfig": {
    },
  • "labels": {
    },
  • "taints": [
    ],
  • "subnetId": "sub-3b7c5f10-e417-4847-bf84-08d03365c61f",
  • "secondarySubnets": [
    ],
  • "enabledEncryptionVolume": false,
  • "dnsServiceConfig": {
    },
  • "placementGroupId": "server-group-06b86747-eaf7-47dd-9e41-579c2e30bfdd"
}

Update node group by ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

nodeGroupId
required
string

ID of the node group

Request Body schema: application/json

Update node group body

numNodes
required
integer <int32> >= 0

The number of nodes to create in this cluster's node group. The number of nodes are between 1 and 10 nodes. If auto_scale_config is set, num_nodes need to be greater than or equal to Minimum node, and less than or equal to Maximum node. If auto_scale_config is not set, num_nodes need to be greater than or equal to 0, and less than or equal to 10.

securityGroups
required
Array of strings [ 1 .. 50 ] items

Specifies the security group for your cluster. A security group acts as a virtual firewall, controlling inbound and outbound traffic for associated resources. You can find the Security Group ID on the vServer Portal and input it here.

imageId
required
string [ 1 .. 50 ] characters [ 1 .. 50 ]

Specifies the image you want to use for your node group. You can obtain the Image ID from the VKS Portal or from this link and enter it in this field. List all of our Image ID in here

object

Labels to be applied to the nodes in the node group. A maximum of 50 labels is allowed. Each label key must have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

Array of objects (NodeGroupTaintDto) <= 50 items

The Kubernetes taints to be applied to the nodes in the node group. Maximum 50 taints are allowed.

object (NodeGroupAutoScaleConfigDto)

Configuration for node group autoscaling

required
object

Upgrade configuration for node group

Responses

Request samples

Content type
application/json
{
  • "numNodes": 3,
  • "securityGroups": [
    ],
  • "imageId": "img-db7784d2-4516-478e-939f-35a04ac50617",
  • "labels": {
    },
  • "taints": [
    ],
  • "autoScaleConfig": {
    },
  • "upgradeConfig": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ng-123",
  • "clusterId": "cluster-123",
  • "name": "my-node-group",
  • "status": "CREATING",
  • "numNodes": 3,
  • "imageId": "image-123",
  • "createdAt": "2023-10-01T12:00:00.000Z",
  • "updatedAt": "2023-10-01T12:00:00.000Z"
}

Delete the node group by ID

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

nodeGroupId
required
string

ID of the node group

query Parameters
forceDelete
boolean
Default: false

Enable force delete node group

Responses

Request samples 

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/node-groups/%7BnodeGroupId%7D',
  qs: {forceDelete: 'SOME_BOOLEAN_VALUE'},
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "ng-123",
  • "clusterId": "cluster-123",
  • "name": "my-node-group",
  • "status": "CREATING",
  • "numNodes": 3,
  • "imageId": "image-123",
  • "createdAt": "2023-10-01T12:00:00.000Z",
  • "updatedAt": "2023-10-01T12:00:00.000Z"
}

Get list of events in a node group

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

nodeGroupId
required
string

ID of the node group

query Parameters
action
string
Default: ""
Example: action=CreateServer

Even action name

page
integer <int32> >= 0
Default: 0
Example: page=0

Page number

pageSize
integer <int32> >= 1
Default: 10
Example: pageSize=10

Page size

type
string
Default: ""
Example: type=Normal

Event type

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/node-groups/%7BnodeGroupId%7D/events',
  qs: {action: 'CreateServer', page: '0', pageSize: '10', type: 'Normal'},
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 150,
  • "page": 0,
  • "pageSize": 10
}

Get list of nodes in the node group

Authorizations:
Authorization
path Parameters
clusterId
required
string

ID of the cluster

nodeGroupId
required
string

ID of the node group

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=0

Page number

pageSize
integer <int32> >= 1
Default: 10
Example: pageSize=10

Page size

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/clusters/%7BclusterId%7D/node-groups/%7BnodeGroupId%7D/nodes',
  qs: {page: '0', pageSize: '10'},
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 150,
  • "page": 0,
  • "pageSize": 10
}

Node Group Image Controller

Get list of node group images

Authorizations:
Authorization

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/node-group-images',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
[
  • {
    }
]

Quota Controller

Get the quota of the user ID

Authorizations:
Authorization

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/quota',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "maxClusters": 10,
  • "numClusters": 3,
  • "maxNodeGroupsPerCluster": 5,
  • "maxNodesPerNodeGroup": 100
}

Workspace Controller

Get the workspace of the user ID

Authorizations:
Authorization

Responses

Request samples 

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://vks.api.vngcloud.vn/v1/workspace',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "projectId": "pro-e28d4501-59d8-4f47-9eb0-948c54f80592",
  • "serviceAccountId": "b2c33d35-1090-4182-af04-40ae428347d3",
  • "status": "ACTIVE",
  • "statusReason": "Provisioning failed due to network issue"
}

Create the workspace

Authorizations:
Authorization

Responses

Request samples 

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://vks.api.vngcloud.vn/v1/workspace',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "error": {
    }
}

Reset the service account for the user ID

Authorizations:
Authorization

Responses

Request samples 

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://vks.api.vngcloud.vn/v1/workspace/reset-service-account',
  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "projectId": "pro-e28d4501-59d8-4f47-9eb0-948c54f80592",
  • "serviceAccountId": "b2c33d35-1090-4182-af04-40ae428347d3",
  • "status": "ACTIVE",
  • "statusReason": "Provisioning failed due to network issue"
}