Querying a Specified Node Pool¶

Function¶

This API is used to query a specified node pool.

Note

The URL for cluster management is in the format of https://Endpoint/uri. In the URL, uri indicates the resource path, that is, the path for API access.
A node pool is a group of nodes within a cluster that all have the same configuration.

URI¶

GET /api/v3/projects/{project_id}/clusters/{cluster_id}/nodepools/{nodepool_id}

Table 1 describes the parameters of this API.

**Table 1** Parameter description¶
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see How to Obtain Parameters in the API URI.
cluster_id	Yes	String	Cluster ID. For details about how to obtain the cluster ID, see How to Obtain Parameters in the API URI.
nodepool_id	Yes	String	Node pool ID. For details about how to obtain the node pool ID, see Listing All Nodes in a Cluster.

**Table 2** Parameter description¶
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see How to Obtain Parameters in the API URI.
errorStatus	No	String	String This field allows a cluster to be in the Error state if exceptions occur when the cluster is being deleted. If the value of errorStatus is null, the cluster stays in the Deleting state, but not Error. Minimum: 0 Maximum: 10
showDefaultNodePool	No	String	String Whether to display the default node pool. By default, the default node pool is not displayed. If this parameter is set to true, the default node pool is displayed.

Request¶

Request parameters:

Table 1 lists the request parameters.

**Table 3** Parameters in the request header¶
Parameter	Mandatory	String	Description
Content-Type	Yes	String	Message body type (format). Default: application/json
X-Auth-Token	Yes	String	Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. For details on how to obtain a user token, see API Usage Guidelines.

Example request:

Response¶

Response parameters:

Table 4 describes the response parameters.

**Table 4** Response parameters¶
Parameter	Type	Description
kind	String	API type. The value is fixed to NodePool.
apiVersion	String	API version. The value is fixed to v3.
items	NodePool object	/

**Table 5** NodePool¶
Parameter	Type	Description
kind	String	API type. The value is fixed to NodePool.
apiVersion	String	API version. The value is fixed to v3.
metadata	metadata object	Node pool metadata.
spec	spec object	Detailed node pool parameters.
status	status object	Node pool status.

**Table 6** Data structure of the metadata field¶
Parameter	Type	Description
name	String	Name of the node pool.
uid	String	ID of the node pool.

**Table 7** Data structure of the spec field¶
Parameter	Type	Description
type	String	Node type. vm: ECS ElasticBMS: BMS. This value is valid in CCE Turbo cluster.
initialNodeCount	Integer	Initial number of nodes for the node pool.
nodeTemplate	nodeTemplate object	Detailed parameters of the node pool template.
autoscaling	autoscaling object	Auto scaling parameters.
nodeManagement	nodeManagement object	Node management parameters.
customSecurityGroups	Array of strings	Custom security group settings for a node pool. New nodes scaled out in a node pool can be bound to a specified security group. Specifying no security group ID will add the new nodes to the default security group of the worker nodes. Specifying a valid security group ID will put new nodes in that security group. When specifying a security group, do not modify the rules of the port on which CCE running depends.

**Table 8** Data structure of the **nodeTemplate** field¶
Parameter	Type	Description
flavor	String	Node specifications. For details, see the description of the flavorRef parameter in Creating an ECS. Note When adding a BMS node, check whether the flavor of the node to be added supports local disks. If local disks are not supported, add at least one 100 GB EVS disk.
az	String	AZ of the node. For details, see the description of the availability_zone parameter in Creating an ECS.
os	String	Node OS.
login	login object	Node login mode, which can be key pair or password.
rootVolume	Volume object	System disk parameters of the node.
dataVolumes	Array of Volume object	Data disk parameters of the node.
storage	Storage object	Disk initialization management parameter. This parameter is complex to configure. For details, see Attaching Disks to a Node. If this parameter retains its default, disks are managed based on the DockerLVMConfigOverride (discarded) parameter in extendParam. This parameter is supported by clusters of version 1.15.11 and later. Note If a node specification involves local disks and EVS disks at the same time, do not retain the default value of this parameter to prevent unexpected disk partitions.
publicIP	publicIP object	EIP used by the node to access public networks.
nodeNicSpec	nodeNicSpec object	Node NIC description.
count	Integer	Number of nodes to be created in a batch. The value must be a positive integer greater than or equal to 1 and less than or equal to the defined limit. Note This fielder can be set to 0 for a node pool.
billingMode	Integer	Billing mode of a node. Note This field is not supported for the current version.
extendParam	extendParam object	Extended parameter. Format: Key-value pair.
userTags	Object	Tag of a VM. The format is key-value pair. The number of key-value pairs cannot exceed 20. Key: Only letters, digits, hyphens (-), underscores (_), and at signs (@) are supported. Value: Only letters, digits, hyphens (-), underscores (_), and at signs (@) are supported. Example: "userTags": [ { "key": "tag1", "value": "aaaa" }, { "key": "tag2", "value": "bbbb" } ]
k8sTags	Object	Tag of a Kubernetes node. The format is key-value pair. The number of key-value pairs cannot exceed 20. Key: Enter 1 to 63 characters starting with a letter or digit. Only letters, digits, hyphens (-), underscores (_), and periods (.) are allowed. A DNS subdomain can be prefixed to a key and contain a maximum of 253 characters. Example DNS subdomain: example.com/my-key Value: The value can be left blank or a string of 1 to 63 characters starting with a letter or digit. Only letters, digits, hyphens (-), underscores (_), and periods (.) are allowed in the character string. Example: "k8sTags": { "key": "value" }
taints	Object	You can add taints to created nodes to configure anti-affinity. Each taint contains the following parameters: Key: A key must contain 1 to 63 characters starting with a letter or digit. Only letters, digits, hyphens (-), underscores (_), and periods (.) are allowed. A DNS subdomain name can be used as the prefix of a key. Value: A value must start with a letter or digit and can contain a maximum of 63 characters, including letters, digits, hyphens (-), underscores (_), and periods (.). Effect: Available options are NoSchedule, PreferNoSchedule, and NoExecute. Example: "taints": [{ "key": "status", "value": "unavailable", "effect": "NoSchedule" }, { "key": "looks", "value": "bad", "effect": "NoSchedule" }]
runtime	Runtime object	Container runtime. The default value is docker.

**Table 9** Data structure of the **login** field¶
Parameter	Type	Description
sshKey	String	Name of the key pair used for node login. For details on how to create a key pair, see Creating a Key Pair.
userPassword	String	Password used for node login. Note This field is not supported for the current version.

**Table 10** Data structure of the **Volume** field¶
Parameter	Type	Description
volumetype	String	Disk type. For details, see the description of root_volume in Creating an ECS. SATA: common I/O disk type. SAS: high I/O disk type. SSD: ultra-high I/O disk type.
size	Integer	Disk size, in GB. Value range for system disks: 40 to 1024. Value range for data disks: 100 to 32768.
extendParam	Map<String,Object>	Disk extension parameter.
hw:passthrough	Boolean	Pay attention to this field if your ECS is SDI-compliant. If the value of this field is true, the created disk is of the SCSI type. If the node pool type is ElasticBMS, this field must be set to true.
metadata	dataVolumeMetadata object	Data disk encryption information. This parameter is mandatory only when the data disk of the node to be created needs to be encrypted. If data disks are created using a data disk image, this parameter cannot be used.

**Table 11** Data structure of the **dataVolumeMetadata** field¶
Parameter	Type	Description
__system__encrypted	String	Whether an EVS disk is encrypted. '0': not encrypted '1': encrypted If this parameter is not specified, EVS disks will not be encrypted by default.
__system__cmkid	String	CMK ID used for encryption. This parameter is used with __system__encrypted. Note You can obtain the ID through HTTPS requests. For details, see Querying the List of CMKs.

**Table 12** Data structure of the **publicIP** field¶
Parameter	Type	Description
ids	Array of strings	List of IDs of the existing EIPs. Important NOTICE: If ids is set, you do not need to set count and eip.
count	Integer	Number of EIPs to be dynamically created. Important NOTICE: The count and eip parameters must be set simultaneously.
eip	eip object	EIP. Important NOTICE: The count and eip parameters must be set simultaneously.

**Table 13** Data structure of the **eip** field¶
Parameter	Type	Description
iptype	String	Type of the EIP.
bandwidth	bandwidth object	Bandwidth parameters of the EIP.

**Table 14** Data structure of the **bandwidth** field¶
Parameter	Type	Description
chargemode	String	Bandwidth billing mode. If this parameter is not carried, the node is billed by bandwidth. If this parameter is carried but is left blank, the node is billed by bandwidth. If this parameter is set to traffic, the node is billed by traffic. If this parameter is set to another value, node creation will fail. Note Billed by bandwidth: The billing will be based on the data transfer rate (in Mbps) of public networks. If your bandwidth usage is higher than 10%, this billing mode is recommended. Billed by traffic: The billing will be based on the total traffic (in GB) transferred on public networks. If your bandwidth usage is lower than 10%, this billing mode is recommended.
size	Integer	Bandwidth size.
sharetype	String	Bandwidth sharing type.

**Table 15** Data structure of the **nodeNicSpec** field¶
Parameter	Type	Description
primaryNic	primaryNic object	Primary NIC description.
extNics	Array of extNics objects	Extension NIC.

**Table 16** Data structure of the primaryNic/extNics field¶
Parameter	Type	Description
subnetId	String	Network ID of the subnet to which the NIC belongs.
fixedIps	Array of strings	The IP address of the primary NIC is specified by fixedIps. The number of IP addresses cannot be greater than the number of created nodes. fixedIps and ipBlock cannot be specified at the same time.
ipBlock	String	CIDR format of the IP address segment. The IP address of the created node falls in this IP address segment. fixedIps and ipBlock cannot be specified at the same time.

**Table 17** Data structure of the spec/extendParam field¶
Parameter	Type	Description
maxPods	Integer	Maximum number of pods on the node.
alpha.cce/preInstall	String	Script required before the installation. Note The input value must be encoded using Base64. (Command: echo -n "Content to be encoded" \| base64)
alpha.cce/postInstall	String	Script required after the installation. Note The input value must be encoded using Base64. (Command: echo -n "Content to be encoded" \| base64)
alpha.cce/NodeImageID	String	Mandatory if a custom image is used in creating a bare metal node.
DockerLVMConfigOverride	String	Docker data disk configuration item. (This parameter has been discarded. Use the storage field instead.)The following is an example configuration: "DockerLVMConfigOverride":"dockerThinpool=vgpaas/90%VG;kubernetesLV=vgpaas/10%VG;diskType=evs;lvType=linear" In this example: userLV: size of the user space, for example, vgpaas/20%VG. userPath: mount path of the user space, for example, /home/wqt-test. diskType: disk type. Currently, only the evs, hdd, and ssd are supported. lvType: type of a logic volume. Currently, the value can be linear or striped. dockerThinpool: Docker space size, for example, vgpaas/60%VG. kubernetesLV: kubelet space size, for example, vgpaas/20%VG.
publicKey	String	Public key of the node. Used when creating a key pair.

**Table 18** Data structure of the autoscaling field¶
Parameter	Type	Description
enable	Boolean	Whether to enable auto scaling. Default: false
minNodeCount	Integer	Minimum number of nodes allowed if auto scaling is enabled. The value cannot be greater than the maximum number of nodes allowed by the cluster specifications. Minimum: 0
maxNodeCount	Integer	Maximum number of nodes allowed if auto scaling is enabled.
scaleDownCooldownTime	Integer	Interval between two scaling operations, in minutes. During this period, nodes added after a scale-up will not be deleted.
priority	Integer	Weight of a node pool. A node pool with a higher weight has a higher priority during scaling.

**Table 19** Data structure of the nodeManagement field¶
Parameter	Type	Description
serverGroupReference	String	ECS group ID. If this parameter is specified, all nodes in the node pool will be created in this ECS group.

**Table 20** Data structure of the status field¶
Parameter	Type	Description
currentNode	Integer	Number of nodes in the node pool.
phase	String	Node pool status. Synchronizing: The node is being synchronized. Synchronized: The node has been synchronized. SoldOut: Nodes have been sold out. Deleting: The node is being deleted. Error: An error occurred when the node is being added. Note If the status is blank, the status is normal.
jobId	String	ID of the job to delete the node pool.

**Table 21** Runtime¶
Parameter	Mandatory	Type	Description
name	No	String	Container runtime. The default value is docker. Enumeration values: docker containerd

**Table 22** Storage¶
Parameter	Type	Description
storageSelectors	Array of StorageSelectors objects	Disk selection. Matched disks are managed according to matchLabels and storageType.
storageGroups	Array of StorageGroups objects	A storage group consists of multiple storage devices. It is used to divide storage space.

**Table 23** StorageSelectors¶
Parameter	Type	Description
name	String	Selector name, used as the index of selectorNames in storageGroup. Therefore, the name of each selector must be unique.
storageType	String	Specifies the storage type. Currently, only evs (EVS volumes) and local (local volumes) are supported. The local storage does not support disk selection. All local disks will form a VG. Therefore, only one storageSelector of the local type is allowed.
matchLabels	matchLabels object	Matching field of an EVS volume. The size, volumeType, metadataEncrypted, metadataCmkid and count fields are supported.

**Table 24** matchLabels¶
Parameter	Type	Description
size	String	Matched disk size. If this parameter is left unspecified, the disk size is not limited. Example: 100
volumeType	String	EVS disk type. Currently, SSD, GPSSD and SAS are supported.
metadataEncrypted	String	Disk encryption identifier. 0 indicates that the disk is not encrypted, and 1 indicates that the disk is encrypted.
metadataCmkid	String	Customer master key ID of an encrypted disk. The value is a 36-byte string.
count	String	Number of disks to be selected. If this parameter is left blank, all disks of this type are selected.

**Table 25** StorageGroups¶
Parameter	Type	Description
name	String	Name of a virtual storage group, which must be unique.
cceManaged	Boolean	Storage space for Kubernetes and runtime components. Only one group can be set to true. If this parameter is left blank, the default value false is used.
selectorNames	Array of strings	This parameter corresponds to name in storageSelectors. A group can match multiple selectors, but a selector can match only one group.
virtualSpaces	Array of VirtualSpace objects	Detailed management of space configuration in a group.

**Table 26** VirtualSpace¶
Parameter	Type	Description
name	String	Name of a virtualSpace. Kubernetes: Kubernetes space configuration. lvmConfig needs to be configured. runtime: runtime space configuration. runtimeConfig needs to be configured. user: user space configuration. lvmConfig needs to be configured.
size	String	Size of a virtualSpace. The value must be an integer in percentage. Example: 90%. Note The sum of the percentages of all virtualSpaces in a group cannot exceed 100%.
lvmConfig	LVMConfig object	LVM configurations, applicable to kubernetes and user spaces. Note that one virtual space supports only one config.
runtimeConfig	RuntimeConfig object	runtime configurations, applicable to the runtime space. Note that one virtual space supports only one config.

**Table 27** LVMConfig¶
Parameter	Type	Description
lvType	String	LVM write mode. linear indicates the linear mode. striped indicates the striped mode, in which multiple disks are used to form a strip to improve disk performance.
path	String	Path to which the disk is attached. This parameter takes effect only in user configuration. The value is an absolute path. Digits, letters, periods (.), hyphens (-), and underscores (_) are allowed.

**Table 28** RuntimeConfig¶
Parameter	Type	Description
lvType	String	LVM write mode. linear indicates the linear mode. striped indicates the striped mode, in which multiple disks are used to form a strip to improve disk performance.

Response example:

{
    "kind": "NodePool",
    "apiVersion": "v3",
    "metadata": {
        "name": "test-nodepool",
        "uid": "65787e3e-cd82-11ea-8ec6-0255ac1001be"
    },
    "spec": {
        "initialNodeCount": 0,
        "type": "vm",
        "nodeTemplate": {
            "flavor": "s6.large.2",
            "az": "",
            "os": "EulerOS 2.5",
            "login": {
                "sshKey": "KeyPair-nodepool",
                "userPassword": {}
            },
            "rootVolume": {
                "volumetype": "SATA",
                "size": 40
            },
            "dataVolumes": [
                {
                    "volumetype": "SATA",
                    "size": 100,
                    "extendParam": {
                        "useType": "docker"
                    },
                    "metadata": {
                        "__system__cmkid": "1ed68cb7-b09b-423c-8d66-fdd2e063769d",
                        "__system__encrypted": "1"
                    }
                }
            ],
            "storage": {
                "storageSelectors": [
                    {
                        "name": "cceUse",
                        "storageType": "evs",
                        "matchLabels": {
                            "size": "100",
                            "volumeType": "SAS",
                            "count": "1"
                        }
                    }
                ],
                "storageGroups": [
                    {
                        "name": "vgpaas",
                        "selectorNames": [
                            "cceUse"
                        ],
                        "cceManaged": true,
                        "virtualSpaces": [
                            {
                                "name": "runtime",
                                "size": "90%"
                            },
                            {
                                "name": "kubernetes",
                                "size": "10%"
                            }
                        ]
                    }
                ]
            },
            "runtime": {
                "name":"docker"
            },
            "publicIP": {
                "eip": {
                    "bandwidth": {}
                }
            },
            "nodeNicSpec": {
                "primaryNic": {
                    "subnetId": "3d6f5dc2-caf7-4a06-b4ac-11a3a5a49cdd"
                }
            },
            "billingMode": 0,
            "taints": [
                {
                    "key": "test-taints",
                    "value": "test",
                    "effect": "NoSchedule"
                }
            ],
            "k8sTags": {
                "cce.cloud.com/cce-nodepool": "test-nodepool",
                "test-k8stag": "test"
            },
            "userTags": [
                {
                    "key": "test-resourcetag",
                    "value": "test"
                }
            ],
            "extendParam": {
                "DockerLVMConfigOverride": "dockerThinpool=vgpaas/90%VG;kubernetesLV=vgpaas/10%VG;diskType=evs;lvType=linear",
                "alpha.cce/NodeImageID": "85bd7ec5-bca4-4f5f-947b-6c1bf02599d3",
                "alpha.cce/postInstall": "bHMgLWwK",
                "alpha.cce/preInstall": "bHMgLWw=",
                "maxPods": 100
            }
        },
        "autoscaling": {
            "enable": true,
            "minNodeCount": 0,
            "maxNodeCount": 4,
            "scaleDownCooldownTime": 5,
            "priority": 1
        },
        "nodeManagement": {
            "serverGroupReference": "2129f95a-f233-4cd8-a1b2-9c0acdf918d3"
        }
    },
    "status": {
        "currentNode": 0,
        "phase": ""
    }
}

Status Code¶

Table 29 describes the status code of this API.

**Table 29** Status code¶
Status Code	Description
200	The specified node pool is queried successfully.

For details about error status codes, see Status Code.

last updated: 2024-11-08 14:16 UTC - commit: 7c478af3470092ad91013d02b08e29c6a61c275d