You can call the CreateClusterNodePool operation to create a node pool for a Container Service for Kubernetes (ACK) cluster.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request syntax

POST /clusters/ClusterId/nodepools HTTP/1.1
Content-Type:application/json

{
  "auto_scaling" : {
    "enable" : Boolean,
    "max_instances" : Long,
    "min_instances" : Long,
    "type" : "String",
    "is_bond_eip" : Boolean,
    "eip_internet_charge_type" : "String",
    "eip_bandwidth" : Long
  },
  "kubernetes_config" : {
    "cms_enabled" : Boolean,
    "cpu_policy" : "String",
    "labels" : [ {
      "key" : "String",
      "value" : "String"
    } ],
    "runtime" : "String",
    "runtime_version" : "String",
    "taints" : [ {
      "key" : "String",
      "value" : "String",
      "effect" : "String"
    } ],
    "user_data" : "String"
  },
  "nodepool_info" : {
    "name" : "String",
    "resource_group_id" : "String"
  },
  "scaling_group" : {
    "auto_renew" : Boolean,
    "auto_renew_period" : Long,
    "data_disks" : [ {
      "category" : "String",
      "size" : Long,
      "encrypted" : "String",
      "auto_snapshot_policy_id" : "String"
    } ],
    "image_id" : "String",
    "instance_charge_type" : "String",
    "instance_types" : [ "String" ],
    "key_pair" : "String",
    "login_password" : "String",
    "period" : Long,
    "period_unit" : "String",
    "platform" : "String",
    "rds_instances" : [ "String" ],
    "spot_strategy" : "String",
    "spot_price_limit" : [ {
      "instance_type" : "String",
      "price_limit" : "String"
    } ],
    "scaling_policy" : "String",
    "security_group_id" : "String",
    "security_group_ids" : [ "String" ],
    "system_disk_category" : "String",
    "system_disk_size" : Long,
    "tags" : [ {
      "key" : "String",
      "value" : "String"
    } ],
    "vswitch_ids" : [ "String" ],
    "multi_az_policy" : "String",
    "on_demand_base_capacity" : Long,
    "on_demand_percentage_above_base_capacity" : Long,
    "spot_instance_pools" : Long,
    "spot_instance_remedy" : Boolean,
    "compensate_with_on_demand" : Boolean,
    "internet_charge_type" : "String",
    "internet_max_bandwidth_out" : Long
  },
  "tee_config" : {
    "tee_enable" : Boolean
  },
  "management" : {
    "enable" : Boolean,
    "auto_repair" : Boolean,
    "upgrade_config" : {
      "auto_upgrade" : Boolean,
      "surge" : Long,
      "surge_percentage" : Long,
      "max_unavailable" : Long
    }
  },
  "count" : Long
}

Request parameters

Table 1. Request path parameters
Parameter Type Required Example Description
ClusterId String Yes c61da77e8bfbc4c4c999af2b51b65****

The ID of the cluster that you want to manage.

Table 2. Request body parameters
Parameter Type Required Example Description
auto_scaling Object No

The configuration about auto scaling.

enable Boolean Yes true

Specifies whether to enable auto scaling. Valid values:

  • true: enables auto scaling.
  • false: disables auto scaling. If you set this parameter to false, other parameters in the auto_scaling section do not take effect.

Default value: false.

max_instances Long Yes 10

The maximum number of Elastic Compute Service (ECS) instances that can be created in the node pool.

min_instances Long Yes 1

The minimum number of ECS instances that must be kept in the node pool.

type String No cpu

The instance types that can be used for the auto scaling of the node pool. Valid values:

  • cpu: regular instance
  • gpu: GPU-accelerated instance
  • gpushare: shared GPU-accelerated instance
  • spot: preemptible instance

Default value: cpu

is_bond_eip Boolean No true

Specifies whether to associate an elastic IP address (EIP) with the node pool. Valid values:

  • true: associates an EIP with the node pool
  • false: does not associate an EIP with the node pool

Default value: false

eip_internet_charge_type String No PayByBandwidth

The billing method of the EIP. Valid values:

  • PayByBandwidth: pay-by-bandwidth
  • PayByTraffic: pay-by-data-transfer

Default value: PayByBandwidth

eip_bandwidth Long No 5

The peak bandwidth of the EIP.

kubernetes_config Object No

The configuration of the cluster.

cms_enabled Boolean No true

Specifies whether to install the CloudMonitor agent on ECS nodes. After the CloudMonitor agent is installed on ECS nodes, you can view monitoring information about the instances in the CloudMonitor console. We recommend that you install the CloudMonitor agent. Valid values:

  • true: installs the CloudMonitor agent on ECS nodes
  • false: does not install the CloudMonitor agent on ECS nodes

Default value: false

cpu_policy String No none

The CPU management policy. The following policies are supported if the Kubernetes version of the cluster is 1.12.6 or later.

  • static: allows pods with specific resource characteristics on the node to be granted with enhanced CPU affinity and exclusivity
  • none: indicates that the default CPU affinity is used.

Default value: none

labels Array of tag No

The labels that you want to add to the nodes in the cluster.

runtime String Yes docker

The container runtime.

runtime_version String Yes 19.03.5

The version of the container runtime.

taints Array of taint No

The taints that you want to add to the nodes.

user_data String No dGhpcyBpcyBhIGV4YW1wbGU=

The user-defined data on the node.

node_name_mode String No aliyun.com00055test

A custom node name consists of a prefix, an IP substring, and a suffix.

  • The prefix and suffix can contain multiple parts that are separated by periods (.). Each part can contain lowercase letters, digits, and hyphens (-). A custom node name must start and end with a digit or lowercase letter.
  • The IP substring length specifies the number of digits to be truncated from the end of the node IP address. The IP substring length ranges from 5 to 12.

For example, if the node IP address is 192.168.0.55, the prefix is aliyun.com, the IP substring length is 5, and the suffix is test, the node name will be aliyun.com00055test.

nodepool_info Object No

The configuration of the node pool.

name String Yes cluster-demo

The name of the node pool.

resource_group_id String No rg-acfmyvw3wjmb****

The ID of the resource group to which the node pool belongs.

type String No ess

The type of the node pool. Valid values:

  • ess: node pool
  • edge: edge node pool.
scaling_group Object No

The configuration of the scaling group that is used by the node pool.

auto_renew Boolean No true

Specifies whether to enable auto-renewal for nodes in the node pool. This parameter takes effect only when you set instance_charge_type to PrePaid. Valid values:

  • true: enables auto-renewal
  • false: disables auto-renewal

Default value: true

auto_renew_period Long No 1

The duration of the auto-renewal. This property takes effect and is required only when you set instance_charge_type to PrePaid and auto_renew to true. If you specify PeriodUnit=Month, the valid values are 1, 2, 3, 6, and 12.

Default value: 1

data_disks Array of data_disk No

The configurations of the data disks that are mounted to the nodes in the node pool.

image_id String No aliyun_2_1903_x64_20G_alibase_20200529.vhd

The ID of a custom image. By default, the image provided by ACK is used.

instance_charge_type String Yes PrePaid

The billing method of the nodes in the node pool. Valid values:

  • PrePaid: subscription
  • PostPaid: the pay-as-you-go

Default value: PostPaid

instance_types Array of String Yes ecs.d1ne.2xlarge

The instance types.

key_pair String No np-key-name

The name of the key pair. You must set this parameter or the login_password parameter.

Note You must set key_pair if the node pool is a managed node pool.
login_password String No Hello1234

The password for SSH logon. You must set this parameter or the key_pair parameter. The password must be 8 to 30 characters in length, and must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters.

period Long No 1

The subscription duration of the nodes in the node pool. This parameter takes effect and is required only when you set instance_charge_type to PrePaid. If you set period_unit to Month, the valid values of period are 1, 2, 3, 6, and 12.

Default value: 1

period_unit String No Month

The billing cycle of the nodes in the node pool. This parameter is required if you set instance_charge_type to PrePaid. A value of Month indicates that the billing cycle is measured in months.

platform String No Linux

The OS distribution that you want to use. Valid values:

  • CentOS
  • AliyunLinux
  • Windows
  • WindowsCore

Default value: AliyunLinux

rds_instances Array of String No rds-****

The IDs of ApsaraDB RDS instances.

spot_strategy String No NoSpot

The type of the preemptible instance. Valid values:

  • NoSpot: non-preemptible instance
  • SpotWithPriceLimit: specifies the highest bid for the preemptible instance
  • SpotAsPriceGo: automatically submits bids based on the up-to-date market price

For more information, see Preemptible instances.

spot_price_limit Array No

The instance type for preemptible instances and the price limit of the instance type.

instance_type String No ecs.c6.large

The instance type of preemptible instances.

price_limit String No 0.39

The maximum bid price of a preemptible instance. Unit: USD/hour.

scaling_policy String No release

The scaling mode of the scaling group. Valid values:

  • release: the standard mode. ECS instances are created and released based on the resource usage.
  • recycle: the swift mode. the swift mode. ECS instances are created, stopped, or started during scaling events. This reduces the time required for the next scale-out event. When the instance is stopped, you are charged only for the storage service. This does not apply to ECS instances attached with local disks.

Default value: release

security_group_id String No sg-wz9a8g2mt6x5llu0****

Specifies the ID of the security group to which you want to add the node pool. You must set this parameter or security_group_ids. We recommend that you set security_group_ids.

security_group_ids Array of String No sg-wz9a8g2mt6x5llu0****

Specifies the IDs of security groups to which you want to add the node pool. You must set this parameter or security_group_id. We recommend that you set security_group_ids. If you set both security_group_id and security_group_ids, security_group_ids is used.

system_disk_category String Yes cloud_efficiency

The type of system disk. Valid values:

  • cloud_efficiency: ultra disk
  • cloud_ssd: standard SSD
  • cloud_essd: enhanced SSD (ESSD)

Default value: cloud_efficiency

system_disk_size Long Yes 120

The system disk size of a node. Unit: GiB.

Valid values: 40 to 500

system_disk_performance_level String No PL1

The performance level (PL) of the system disk that you want to use for the node. This parameter takes effect only for ESSDs.

tags Array No

The labels that you want to add to the ECS instances.

A key must be unique and cannot exceed 128 characters in length. Neither keys nor values can start with aliyun or acs:. Neither keys nor values can contain https:// or http://.

key String No node-k-1

The key of the label.

value String No node-v-1

The value of the label.

vswitch_ids Array of String Yes vsw-wz9mfnhmssud6eicu****

The IDs of vSwitches.

multi_az_policy String No COST_OPTIMIZED

The ECS instance scaling policy for a multi-zone scaling group. Valid values:

  • PRIORITY: the scaling group is scaled based on the VSwitchIds.N parameter. If an ECS instance cannot be created in the zone where the vSwitch that has the highest priority resides, Auto Scaling creates the ECS instance in the zone where the vSwitch that has the next highest priority resides.
  • COST_OPTIMIZED: ECS instances are created based on the vCPU unit price in ascending order. Preemptible instances are preferably created when preemptible instance types are specified in the scaling configuration. You can set the CompensateWithOnDemand parameter to specify whether to automatically create pay-as-you-go instances when preemptible instances cannot be created due to insufficient resources.
    Note COST_OPTIMIZED is valid only when multiple instance types are specified or at least one preemptible instance type is specified.
  • BALANCE: ECS instances are evenly distributed across multiple zones specified by the scaling group. If ECS instances become imbalanced among multiple zones due to insufficient inventory, you can call RebalanceInstances of Auto Scaling to balance the instance distribution among zones.

Default value: PRIORITY

on_demand_base_capacity Long No 0

The minimum number of pay-as-you-go instances that must be kept in the scaling group. Valid values: 0 to 1000. If the number of pay-as-you-go instances is less than the value of this parameter, Auto Scaling preferably creates pay-as-you-go instances.

on_demand_percentage_above_base_capacity Long No 20

The percentage of pay-as-you-go instances among the extra instances that exceed the number specified by on_demand_base_capacity. Valid values: 0 to 100.

spot_instance_pools Long No 5

The number of instance types that are available. Auto Scaling creates preemptible instances of multiple instance types that are available at the lowest cost. Valid values: 1 to 10

spot_instance_remedy Boolean No false

Specifies whether to supplement preemptible instances. If you set the value to true, Auto Scaling attempts to create a new preemptible instance when the system notifies that an existing preemptible instance is to about to be reclaimed. Valid values:

  • true: enables the supplementation of preemptible instances
  • false: disables the supplementation of preemptible instances
compensate_with_on_demand Boolean No true

Specifies whether to automatically create pay-as-you-go instances to meet the required number of ECS instances if preemptible instances cannot be created due to reasons such as the cost or insufficient inventory. This parameter takes effect when you set multi_az_policy to COST_OPTIMIZED. Valid values:

  • true: automatically creates pay-as-you-go instances to meet the required number of ECS instances if preemptible instances cannot be created
  • false: does not create pay-as-you-go instances to meet the required number of ECS instances if preemptible instances cannot be created
internet_charge_type String No PayByTraffic

The billing method of the public IP address. Valid values:

  • PayByBandwidth: pay-by-bandwidth
  • PayByTraffic: pay-by-data-transfer
internet_max_bandwidth_out Long No 5

The maximum outbound bandwidth of the public IP address of the node. Unit: Mbit/s. Valid values: 1 to 100.

image_type String No AliyunLinux

The type of OS image. You must set this parameter or platform. Valid values:

  • AliyunLinux: Alinux2
  • AliyunLinux3: Alinux3
  • AliyunLinux3Arm64: Alinux3 ARM
  • AliyunLinuxUEFI: Alinux2 UEFI
  • CentOS: CentOS
  • Windows: Windows
  • WindowsCore: Windows Core
  • ContainerOS: ContainerOS
deploymentset_id String No ds-bp1d19mmbsv3jf6xxxxx

The ID of the deployment set to which the ECS instances in the node pool belong.

desired_size Long No 0

The expected number of nodes in the node pool.

tee_config Object No

The configuration about confidential computing for the cluster.

tee_enable Boolean Yes true

Specifies whether to enable confidential computing for the cluster.

management Object No

The configuration about the managed node pool feature.

enable Boolean Yes false

Specifies whether to enable the managed node pool feature. Valid values:

  • true: enables the managed node pool feature
  • false: disables the managed node pool feature. Other parameters in this section take effect only when you specify enable=true.
auto_repair Boolean No false

Specifies whether to enable auto repair. This parameter takes effect only when you specify enable=true.

  • true: enables auto repair
  • false: disables auto repair
upgrade_config Object No

The configurations about auto upgrade. The configurations take effect only when you specify enable=true.

auto_upgrade Boolean No false

Specifies whether to enable auto upgrade. Valid values:

  • true: enables auto upgrade
  • false: disables auto upgrade
surge Long No 0

The number of additional nodes.

surge_percentage Long No 0

The percentage of additional nodes to the nodes in the node pool. You must set this parameter or surge.

max_unavailable Long Yes 1

The maximum number of nodes that can be in the Unschedulable state.

Valid values: 1 to 1000

Default value: 1

count Long No 1

The number of nodes in the node pool.

interconnect_mode String No basic

The network type of the edge node pool. This parameter takes effect only when you set the type parameter of the node pool to edge. Valid values:

  • basic: basic
  • improved: enhanced
interconnect_config Object No

The configuration of the edge node pool.

cen_id String No cen-ey9k9nfhz0f*******

The ID of the Cloud Enterprise Network (CEN) instance that is associated with the enhanced edge node pool.

ccn_id String No ccn-qm5i0i0q9yi*******

The ID of the Cloud Connect Network (CCN) instance that is associated with the enhanced edge node pool.

ccn_region_id String No cn-shanghai

The region to which the CCN instance that is with the enhanced edge node pool belongs.

bandwidth Long No 10

The bandwidth of the enhanced edge node pool. Unit: M.

improved_period String No 1

The subscription duration of the enhanced edge node pool. The duration is measured in months.

max_nodes Long No 10

The maximum number of nodes that can be created in the edge node pool. You must specify a value that is equal to or larger than 0. A value of 0 indicates that the number of nodes in the node pool is limited only by the quota of nodes in the cluster. In most cases, this parameter is set to a value larger than 0 for edge node pools. This parameter is set to 0 for node pools of the ess type or default edge node pools.

Response syntax

HTTP/1.1 200
Content-Type:application/json
{
  "nodepool_id" : "String"
}

Response parameters

Table 3. Response body parameters
Parameter Type Example Description
nodepool_id String np31da1b38983f4511b490fc62108a****

The ID of the node pool.

Examples

Sample requests

POST /clusters/c61da77e8bfbc4c4c999af2b51b65****/nodepools HTTP/1.1
Host:cs.aliyuncs.com
Content-Type:application/json

{
  "auto_scaling" : {
    "enable" : true,
    "max_instances" : 10,
    "min_instances" : 1,
    "type" : "cpu",
    "is_bond_eip" : true,
    "eip_internet_charge_type" : "PayByBandwidth",
    "eip_bandwidth" : 5
  },
  "kubernetes_config" : {
    "cms_enabled" : true,
    "cpu_policy" : "none",
    "labels" : [ {
      "key" : "env",
      "value" : "prod"
    } ],
    "runtime" : "docker",
    "runtime_version" : "19.03.5",
    "taints" : [ {
      "key" : "key",
      "value" : "value",
      "effect" : "NoSchedule"
    } ],
    "user_data" : "dGhpcyBpcyBhIGV4YW1wbGU=",
    "node_name_mode" : "aliyun.com00055test"
  },
  "nodepool_info" : {
    "name" : "cluster-demo",
    "resource_group_id" : "rg-acfmyvw3wjmb****",
    "type" : "ess"
  },
  "scaling_group" : {
    "auto_renew" : true,
    "auto_renew_period" : 1,
    "data_disks" : [ {
      "category" : "cloud_ssd",
      "size" : 40,
      "encrypted" : "true",
      "auto_snapshot_policy_id" : "sp-2zej1nogjvovnz4z****",
      "performance_level" : "PL1"
    } ],
    "image_id" : "aliyun_2_1903_x64_20G_alibase_20200529.vhd",
    "instance_charge_type" : "PrePaid",
    "instance_types" : [ "ecs.d1ne.2xlarge" ],
    "key_pair" : "np-key-name",
    "login_password" : "Hello1234",
    "period" : 1,
    "period_unit" : "Month",
    "platform" : "Linux",
    "rds_instances" : [ "rds-****" ],
    "spot_strategy" : "NoSpot",
    "spot_price_limit" : [ {
      "instance_type" : "ecs.c6.large",
      "price_limit" : "0.39"
    } ],
    "scaling_policy" : "release",
    "security_group_id" : "sg-wz9a8g2mt6x5llu0****",
    "security_group_ids" : [ "sg-wz9a8g2mt6x5llu0****" ],
    "system_disk_category" : "cloud_efficiency",
    "system_disk_size" : 120,
    "system_disk_performance_level" : "PL1",
    "tags" : [ {
      "key" : "node-k-1",
      "value" : "node-v-1"
    } ],
    "vswitch_ids" : [ "vsw-wz9mfnhmssud6eicu****" ],
    "multi_az_policy" : "COST_OPTIMIZED",
    "on_demand_base_capacity" : 0,
    "on_demand_percentage_above_base_capacity" : 20,
    "spot_instance_pools" : 5,
    "spot_instance_remedy" : false,
    "compensate_with_on_demand" : true,
    "internet_charge_type" : "PayByTraffic",
    "internet_max_bandwidth_out" : 5,
    "image_type" : "AliyunLinux",
    "deploymentset_id" : "ds-bp1d19mmbsv3jf6xxxxx"
  },
  "tee_config" : {
    "tee_enable" : true
  },
  "management" : {
    "enable" : false,
    "auto_repair" : false,
    "upgrade_config" : {
      "auto_upgrade" : false,
      "surge" : 0,
      "surge_percentage" : 0,
      "max_unavailable" : 0
    }
  },
  "count" : 1,
  "interconnect_mode" : "basic",
  "interconnect_config" : {
    "cen_id" : "cen-ey9k9nfhz0f*******",
    "ccn_id" : "ccn-qm5i0i0q9yi*******",
    "ccn_region_id" : "cn-shanghai",
    "bandwidth" : 10,
    "improved_period" : "1"
  },
  "max_nodes" : 10
}

Description of the sample request

Create a node pool that has auto scaling enabled:
{
    "ClusterId":"c61da77e8bfbc4c4c999af2b51b65****",
    "nodepool_info":{
        "name":"autoScale-demo",
        "resource_group_id":"rg-acfmyvw3wjm****"
    },
    "scaling_group":{
        "vswitch_ids":[
            "vsw-wz9mfnhmssud6eic****"
        ],
        "system_disk_category":"cloud_efficiency",
        "system_disk_size":120,
        "data_disks":[

        ],
        "instance_types":[
            "ecs.t6-c1m2.large"
        ],
        "vpc_id":"vpc-wz984yvbd6lck22z3****",
        "tags":[

        ],
        "instance_charge_type":"PostPaid",
        "login_password":"****",
        "platform":"AliyunLinux",
        "image_id":"aliyun_2_1903_x64_20G_alibase_20200529.vhd",
        "rds_instances":[

        ],
        "scaling_policy":"release"
    },
    "kubernetes_config":{
        "cpu_policy":"none",
        "cms_enabled":false,
        "labels":[
            {
                "key":"workload_type",
                "value":"cpu"
            }
        ],
        "taints":[

        ],
        "user_data":"",
        "runtime":"docker",
        "runtime_version":"19.03.5"
    },
    "tee_config":{
        "tee_enable":true
    },
    "auto_scaling":{
        "enable":true,
        "max_instances":10,
        "min_instances":1,
        "type":"cpu"
    }
}

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<nodepool_id>np31da1b38983f4511b490fc62108a****</nodepool_id>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "nodepool_id" : "np31da1b38983f4511b490fc62108a****"
}

Error codes

For a list of error codes, visit the API Error Center.