On this page

Function
Debugging
URI
Request Parameters
Response Parameters
Example Requests
Example Responses
Status Codes
Error Codes

Show all

Help Center/ ModelArts/ API Reference/ Resource Management/ Creating Resource Pools

Creating Resource Pools

Updated on 2025-03-14 GMT+08:00

View PDF

Function

This API is used to create resource pools.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

POST /v2/{project_id}/pools

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details, see Obtaining a Project ID and Name.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-ModelArts-User-ID	No	String	Tenant ID. If there is a tenant ID, it will be used for workspace authentication.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
apiVersion	Yes	String	API version. Options: v2
kind	Yes	String	Resource type. Options: Pool: resource pool
metadata	Yes	PoolMetadataCreation object	Metadata of a resource pool.
spec	No	PoolSpecCreation object	Description of a resource pool.

**Table 4** PoolMetadataCreation
Parameter	Mandatory	Type	Description
labels	Yes	PoolLabelsCreation object	Resource pool labels.
annotations	No	PoolAnnotationsCreation object	Resource pool annotations.

**Table 5** PoolLabelsCreation
Parameter	Mandatory	Type	Description
os.modelarts/name	Yes	String	Name of a resource pool specified by a user.
os.modelarts/workspace.id	No	String	Workspace ID If no workspace is created, the default value is 0. If a workspace is created and used, the actual value prevails.
os.modelarts/node.prefix	No	String	User-defined node name prefix.

**Table 6** PoolAnnotationsCreation
Parameter	Mandatory	Type	Description
os.modelarts/description	No	String	Description of a resource pool.
os.modelarts/billing.mode	No	String	Charging mode. The options are as follows: 0: Pay per use 1: Yearly/Monthly
os.modelarts/period.num	No	String	Duration-based subscription period, for example, 2. This parameter is mandatory when Billing Mode is set to Yearly/Monthly.
os.modelarts/period.type	No	String	Yearly/Monthly subscription type. The options are as follows: 2: month 3: year This parameter is mandatory when the billing mode is yearly/monthly.
os.modelarts/auto.renew	No	String	Whether to enable auto-renewal. The options are as follows: 0: auto-renewal disabled (default value)
os.modelarts/auto.pay	No	String	Specifies whether to automatically pay for a resource. This parameter takes effect only when a user purchases a yearly/monthly resource. The options are: true: yes false: manual payment (default value)
os.modelarts/promotion.info	No	String	Discount information selected by a subscriber in the CBC.
os.modelarts/service.console.url	No	String	URL of the page that is displayed after the subscription order is paid.
os.modelarts/order.id	No	String	Specifies the order ID. This parameter is mandatory when a yearly/monthly pool is created or the billing mode is changed.

**Table 7** PoolSpecCreation
Parameter	Mandatory	Type	Description
type	Yes	String	Resource pool type. The options are as follows: Dedicate: physical resource pool, which uses a separate network and supports network connection, custom drivers, and custom job types.
scope	Yes	Array of strings	Job type supported by a resource pool. You must select at least one standard resource pool when creating a standard resource pool. You can select all physical resource pools. Options: Train: training job Infer: inference job Notebook: Notebook job
resources	Yes	Array of PoolResourceFlavor objects	List of resource specifications in the resource pool, including resource specifications and the number of resources of the corresponding specifications.
network	Yes	network object	Network settings for a resource pool. This parameter is mandatory when you create a physical resource pool.
jobFlavors	No	Array of strings	List of job specifications supported by the resource pool. The content is the job specification name.
driver	No	PoolDriver object	Indicates the driver information of the resource pool.

**Table 8** PoolResourceFlavor
Parameter	Mandatory	Type	Description
flavor	Yes	String	Resource flavor, for example, modelarts.vm.gpu.tnt004.
count	Yes	Integer	Guaranteed resource amount of a resource specification.
maxCount	No	Integer	Elastic resource amount of a resource specification. The value of this parameter must be the same as that of count in the physical pool.
extendParams	No	extendParams object	Customized configuration parameter.
os	No	Os object	Customize the OS image information.

**Table 9** extendParams
Parameter	Mandatory	Type	Description
dockerBaseSize	No	String	Specify the container engine space size of a resource pool node. The value 0 indicates that the size is not limited.

**Table 10** Os
Parameter	Mandatory	Type	Description
name	No	String	OS name
imageId	No	String	OS image ID
imageType	No	String	OS image type. private: private image

**Table 11** network
Parameter	Mandatory	Type	Description
name	Yes	String	Specifies the network name, that is, the value of metadata.name in the network details. When a user interface creates a network by specifying the network name, the system automatically creates a subnet. The user cannot create a subnet. By default, the system is created under the first subnet.

**Table 12** PoolDriver
Parameter	Mandatory	Type	Description
gpuVersion	No	String	GPU driver version. This parameter is available when GPUs are used in a physical resource pool. For example, the GPU driver version is 440.33.
npuVersion	No	String	NPU driver version. This parameter is mandatory when the physical resource pool contains ascend specifications, for example, C78.
updateStrategy	No	String	Indicates the driver upgrade policy. The options are as follows: force: forcible upgrade. The node driver is upgraded immediately, which may affect the running jobs on the node. idle: secure upgrade. The driver is upgraded when no job is running on the node.

Response Parameters

Status code: 200

**Table 13** Response body parameters
Parameter	Type	Description
apiVersion	String	API version. The options are as follows: v2
kind	String	Resource type. The options are as follows: Pool: resource pool
metadata	PoolMetadata object	Specifies the metadata of the resource pool.
spec	PoolSpecModel object	Expected information about a resource pool.
status	PoolStatus object	Status of a resource pool.

**Table 14** PoolMetadata
Parameter	Type	Description
name	String	Automatically generated resource pool name, which is equivalent to pool ID.
creationTimestamp	String	Timestamp, for example, 2021-11-01T03:49:41Z.
labels	PoolMetaLabels object	Resource pool labels.
annotations	PoolMetaAnnotations object	Resource pool annotations.

**Table 15** PoolMetaLabels
Parameter	Type	Description
os.modelarts/workspace.id	String	Workspace ID If no workspace is created, the default value is 0. If a workspace is created and used, the actual value prevails.
os.modelarts/name	String	Specified resource pool name.
os.modelarts/resource.id	String	ID of the primary resource in the resource pool, which is usually provided for CBC.
os.modelarts/tenant.domain.id	String	ID of the tenant corresponding to the resource pool, which records the tenant account where the resource pool is created

**Table 16** PoolMetaAnnotations
Parameter	Type	Description
os.modelarts/description	String	Description of a resource pool.
os.modelarts/billing.mode	String	Billing mode. The options are as follows: 0: Pay per use 1: Yearly/Monthly
os.modelarts/period.num	String	Subscription period on a yearly/monthly basis, for example, 2.
os.modelarts/period.type	String	Yearly/Monthly subscription type. The options are as follows: 2: month 3: year 4: hour
os.modelarts/auto.renew	String	Whether to automatically renew the subscription. Options: 0: auto-renewal disabled (default value) 1: auto-renewal enabled
os.modelarts/promotion.info	String	Discount selected in CBC.
os.modelarts/service.console.url	String	URL of the page displayed after the subscription order is paid.
os.modelarts/order.id	String	Order ID, which is mandatory when creating a yearly/monthly resource pool or changing its billing mode.
os.modelarts/flavor.resource.ids	String	Specifies the resource ID corresponding to each flavor, which is used for interaction with CBC.
os.modelarts/tms.tags	String	TMS tag specified by the user during creation.

**Table 17** PoolSpecModel
Parameter	Type	Description
type	String	Resource pool type. The options are as follows: Dedicate: physical resource pool, which uses a separate network and supports network connection, custom drivers, and custom job types.
scope	Array of strings	Job type supported by the resource pool. Select at least one type. You can select all physical resource pools. The options are as follows: Train: training job Infer: inference job Notebook: Notebook job
resources	Array of resources objects	List of resource specifications in the resource pool, including resource specifications and the number of resources of the corresponding specifications.
network	network object	Specifies the network parameters of the resource pool. This parameter is mandatory for physical resource pools.
jobFlavors	Array of strings	List of job specifications supported by the resource pool. The content is the job specification name.
driver	PoolDriver object	Indicates the driver information of the resource pool.
controlMode	Integer	Restriction status of a resource pool. The options are as follows: 0: not restricted 1: Changing to the yearly/monthly billing is restricted. 2: Modifying specifications is restricted. 4: The service is restricted. 8: frozen 16: The resource pool is frozen by the public security department (cannot be unsubscribed). In addition, multiple statuses are allowed. For example, a resource pool is in state 9, indicating that it is frozen and changing its billing mode to yearly/monthly is restricted.

**Table 18** resources
Parameter	Type	Description
flavor	String	Resource flavor, for example, modelarts.vm.gpu.tnt004.
count	Integer	Number of resources of the corresponding specifications.
azs	Array of PoolNodeAz objects	Specifies the AZ list.
extendParams	extendParams object	Customize the parameter configurations.
os	Os object	OS image information.

**Table 19** PoolNodeAz
Parameter	Type	Description
az	String	AZ name
count	Integer	Specifies the number of nodes in a specified AZ when capacity expansion is performed in a specified AZ.

**Table 20** extendParams
Parameter	Type	Description
dockerBaseSize	String	Specify the container engine space size of a resource pool node. The value 0 indicates that the size is not limited.

**Table 21** Os
Parameter	Type	Description
name	String	OS name
imageId	String	OS image ID
imageType	String	OS image type. private: private image

**Table 22** network
Parameter	Type	Description
name	String	Specifies the network name. When a user interface creates a network by specifying the network name, the system automatically creates a subnet. Users cannot create a subnet. By default, the system is created under the first subnet.

**Table 23** PoolDriver
Parameter	Type	Description
gpuVersion	String	GPU driver version. This parameter is available when GPUs are used in a physical resource pool. For example, the GPU driver version is 440.33.
npuVersion	String	NPU driver version. This parameter is mandatory when the physical resource pool contains ascend specifications, for example, C78.
updateStrategy	String	Indicates the driver upgrade policy. The options are as follows: force: forcible upgrade. The node driver is upgraded immediately, which may affect the running jobs on the node. idle: secure upgrade. The driver is upgraded when no job is running on the node.

**Table 24** PoolStatus
Parameter	Type	Description
phase	String	Resource pool cluster status. The options are as follows: Creating: It is being created. Running: It is running. Abnormal: The resource pool malfunctions. Deleting: It is being deleted. Error: An error occurred in the resource pool.
message	String	Message indicating that the resource pool is in the current state.
resources	resources object	Number of resources in different states in a resource pool.
scope	Array of scope objects	Service status of a resource pool.
driver	driver object	Resource pool driver.
parent	String	Name of the parent node in the resource pool. This parameter is left blank for physical pools.
root	String	Name of the root node in the resource pool. For a physical pool, set this parameter to its own name.

**Table 25** resources
Parameter	Type	Description
creating	PoolResourceFlavorCount object	Number of resources that are being created.
available	PoolResourceFlavorCount object	Number of available resources.
abnormal	PoolResourceFlavorCount object	Number of unavailable resources.
deleting	PoolResourceFlavorCount object	Number of resources that are being deleted.

**Table 26** PoolResourceFlavorCount
Parameter	Type	Description
flavor	String	Resource flavor name, for example, modelarts.vm.gpu.tnt004.
count	Integer	Indicates the guaranteed usage of specifications.
maxCount	Integer	Elastic usage of the resource specification. The value of this parameter is the same as that of count in the physical pool.
azs	Array of azs objects	Number of AZs where the resource is located.
nodePool	String	Node pool name, for example, nodePool-1.

**Table 27** azs
Parameter	Type	Description
az	String	Name of an AZ.
count	Integer	Resources of an AZ.

**Table 28** scope
Parameter	Type	Description
scopeType	String	Service type. The options are as follows: Train: training task Infer: inference task Notebook: Notebook job
state	String	Service status. Options: Enabling: The service is being enabled. Enabled: The service is enabled. Disabling: The service is being disabled. Disabled: The service is disabled.

**Table 29** driver
Parameter	Type	Description
gpu	PoolDriverStatus object	GPU driver.
npu	PoolDriverStatus object	NPU driver.

**Table 30** PoolDriverStatus
Parameter	Type	Description
version	String	Indicates the current driver version.
state	String	Indicates the current driver status. Options: Creating: The gateway is being created. Upgrading: The upgrade is in progress. Running Abnormal: abnormal

Status code: 400

**Table 31** Response body parameters
Parameter	Type	Description
error_code	String	Error codes of ModelArts.
error_msg	String	Error message.

Status code: 409

**Table 32** Response body parameters
Parameter	Type	Description
error_code	String	Error codes of ModelArts.
error_msg	String	Error message.

Example Requests

The following is an example of how to create a dedicated resource pool whose resource type is Pool, pool name is pool-001, pool type is Dedicate (physical resource pool), and supported job type is Train.

POST https://{endpoint}/v2/{project_id}/pools

{
  "kind" : "Pool",
  "apiVersion" : "v2",
  "metadata" : {
    "labels" : {
      "os.modelarts/name" : "pool-001",
      "os.modelarts/workspace.id" : "0"
    },
    "annotations" : {
      "os.modelarts/description" : "",
      "os.modelarts/billing.mode" : "0"
    }
  },
  "spec" : {
    "type" : "Dedicate",
    "scope" : [ "Train" ],
    "network" : {
      "name" : "net-0123-86c13962597848eeb29c5861153a391f"
    },
    "resources" : [ {
      "flavor" : "modelarts.vm.gpu.tnt004",
      "count" : 2
    } ],
    "driver" : {
      "gpuVersion" : "440.31"
    }
  }
}

Example Responses

Status code: 400

Bad request

{
  "error_code" : "ModelArts.50004000",
  "error_msg" : "Bad request"
}

Status code: 409

Already exists

{
  "error_code" : "ModelArts.50015000",
  "error_msg" : "Pool already exists."
}

Status Codes

Status Code	Description
200	OK
400	Bad request
409	Already exists

Error Codes

See Error Codes.

Parent topic: Resource Management

Previous topic: Querying the Real-Time Resource Usage

Next topic: This interface is used to query the resource pool list. You can query the resource pool list by tag or resource pool status.

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot