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-08-20 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 For details about how to obtain the value, see Querying the Workspace List. 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	Definition: OS name. Constraints: N/A Range: N/A Default Value: N/A
imageId	No	String	Definition: OS image ID. Constraints: N/A Range: N/A Default Value: N/A
imageType	No	String	Definition: OS image type. Constraints: N/A Range: private: private image Default Value: N/A

**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	Definition: Default GPU driver version of a resource pool. Constraints: This parameter is valid only when the physical resource pool contains GPU specifications. Range: N/A Default Value: N/A
npuVersion	No	String	Definition: Default NPU driver version of a resource pool. Constraints: This parameter is valid only when the physical resource pool contains NPU specifications. Range: N/A Default Value: N/A
updateStrategy	No	String	Definition: Driver upgrade policy of a resource pool. Constraints: N/A Range: force: forcible upgrade. The node drivers are upgraded immediately, which may affect jobs running on the node. idle: secure upgrade. The drivers are upgraded when no job is running on the node. Default Value: N/A

Response Parameters

Status code: 200

**Table 13** Response body parameters
Parameter	Type	Description
apiVersion	String	Definition: API version of a resource. Constraints: N/A Range: v2: The current resource version is v2. Default Value: N/A
kind	String	Definition: Resource type. Constraints: N/A Range: Pool: resource pool Default Value: N/A
metadata	PoolMetadata object	Definition: Metadata of the resource pool. Constraints: N/A Range: N/A Default Value: N/A
spec	PoolSpecModel object	Definition: Specifications of a resource pool. Constraints: N/A Range: N/A Default Value: N/A
status	PoolStatus object	Definition: Status of a resource pool. Constraints: N/A Range: N/A Default Value: N/A

**Table 14** PoolMetadata
Parameter	Type	Description
name	String	Definition: Resource pool ID. Constraints: N/A Range: N/A Default Value: N/A
creationTimestamp	String	Definition: Time when a resource pool is created. For example, 2025-11-01T03:49:41Z. Constraints: N/A Range: N/A Default Value: N/A
labels	PoolMetaLabels object	Definition: Tags of a resource pool. Constraints: N/A Range: N/A Default Value: N/A
annotations	PoolMetaAnnotations object	Definition: Comments of a resource pool. Constraints: N/A Range: N/A Default Value: N/A

**Table 15** PoolMetaLabels
Parameter	Type	Description
os.modelarts/workspace.id	String	Definition: Workspace ID. For details about how to obtain the ID, see Querying the Workspace List. Constraints: N/A Range: N/A Default Value: 0
os.modelarts/name	String	Definition: Displayed name of a resource pool. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/resource.id	String	Definition: Resource ID used for resource pool billing. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/tenant.domain.id	String	Definition: ID of the tenant to which a resource pool belongs. Constraints: N/A Range: N/A Default Value: N/A

**Table 16** PoolMetaAnnotations
Parameter	Type	Description
os.modelarts/description	String	Definition: Resource pool description. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/billing.mode	String	Definition: Billing mode. Constraints: N/A Range: 0: pay-per-use 1: yearly/monthly Default Value: N/A
os.modelarts/period.num	String	Definition: Subscription period of a yearly/monthly resource pool. Constraints: This parameter is used together with the os.modelarts/period.type field. Range: N/A Default Value: N/A
os.modelarts/period.type	String	Definition: Subscription type of a yearly/monthly resource pool. Constraints: This parameter is used together with the os.modelarts/period.num field. Range: 2: monthly 3: yearly Default Value: N/A
os.modelarts/auto.renew	String	Definition: Auto-renewal status of a yearly/monthly resource pool. Constraints: N/A Range: 0: Auto-renewal is disabled. 1: Auto-renewal is enabled. Default Value: 0
os.modelarts/promotion.info	String	Definition: Discount information selected when a yearly/monthly resource pool is purchased. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/service.console.url	String	Definition: URL to which you are redirected after the order of a yearly/monthly resource pool is paid. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/order.id	String	Definition: Order ID transferred when a yearly/monthly resource pool is purchased. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/flavor.resource.ids	String	Definition: Resource ID of the resource specifications in a yearly/monthly resource pool. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/tms.tags	String	Definition: Resource tags of a resource pool. Constraints: N/A Range: N/A Default Value: N/A

**Table 17** PoolSpecModel
Parameter	Type	Description
type	String	Definition: Resource pool type. Constraints: N/A Range: Dedicate: physical resource pool, which uses a separate network and supports network connection, custom drivers, and custom job types. Logical: logical resource pool. There is no independent network and network connectivity is not supported. Logical resource pools can be created and scaled faster than physical resource pools. Default Value: N/A
scope	Array of strings	Definition: Job types supported by a resource pool. Constraints: N/A Range: Train: training jobs Infer: inference jobs Notebook: notebook jobs Default Value: N/A
resources	Array of resources objects	Definition: Resource specifications in a resource pool, including resource specifications and the number of resources for each specification. Constraints: At least one resource must be contained. Range: N/A Default Value: N/A
network	network object	Definition: Network parameters of a resource pool. Constraints: This parameter is mandatory for physical resource pools. Range: N/A Default Value: N/A
jobFlavors	Array of strings	Definition: Job specifications supported by a resource pool. The value is the job specification name. Constraints: N/A Range: N/A Default Value: N/A
driver	PoolDriver object	Definition: Resource pool driver information. Constraints: N/A Range: N/A Default Value: N/A
controlMode	Integer	Definition: Restriction status of a resource pool. Multiple statuses are allowed. For example, 9 indicates that it is frozen and changing its billing mode to yearly/monthly is restricted. Constraints: N/A Range: 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). Default Value: N/A

**Table 18** resources
Parameter	Type	Description
flavor	String	Definition: Resource flavor ID. Constraints: N/A Range: N/A Default Value: N/A
count	Integer	Definition: Number of resource specification instances in a resource pool. Constraints: N/A Range: N/A Default Value: N/A
azs	Array of PoolNodeAz objects	Definition: AZ distribution of the resource specification instances to be created in the resource pool. Constraints: N/A Range: N/A Default Value: N/A
extendParams	extendParams object	Definition: Custom parameters of a resource pool. Constraints: N/A Range: N/A Default Value: N/A
os	Os object	Definition: OS image information of nodes in a resource pool. Constraints: N/A Range: N/A Default Value: N/A

**Table 19** extendParams
Parameter	Type	Description
dockerBaseSize	String	Definition: Container engine space of a node created in a resource pool. The value 0 indicates that the size is not limited. Constraints: N/A Range: N/A Default Value: N/A

**Table 20** Os
Parameter	Type	Description
name	String	Definition: OS name. Constraints: N/A Range: N/A Default Value: N/A
imageId	String	Definition: OS image ID. Constraints: N/A Range: N/A Default Value: N/A
imageType	String	Definition: OS image type. Constraints: N/A Range: private: private image Default Value: N/A

**Table 21** network
Parameter	Type	Description
name	String	Definition: Network ID. Constraints: N/A Range: N/A Default Value: N/A

**Table 22** PoolDriver
Parameter	Type	Description
gpuVersion	String	Definition: Default GPU driver version of a resource pool. Constraints: This parameter is valid only when the physical resource pool contains GPU specifications. Range: N/A Default Value: N/A
npuVersion	String	Definition: Default NPU driver version of a resource pool. Constraints: This parameter is valid only when the physical resource pool contains NPU specifications. Range: N/A Default Value: N/A
updateStrategy	String	Definition: Driver upgrade policy of a resource pool. Constraints: N/A Range: force: forcible upgrade. The node drivers are upgraded immediately, which may affect jobs running on the node. idle: secure upgrade. The drivers are upgraded when no job is running on the node. Default Value: N/A

**Table 23** PoolStatus
Parameter	Type	Description
phase	String	Definition: Resource pool status. Constraints: N/A Range: Creating: The resource pool is being created. Running: The resource pool is running. Abnormal: The resource pool is abnormal. Deleting: The resource pool is being deleted. Error: An error occurred in the resource pool. Default Value: N/A
message	String	Definition: Prompt information about the resource pool status. Constraints: N/A Range: N/A Default Value: N/A
resources	resources object	Definition: Resource information in different states of the resource pool. Constraints: N/A Range: N/A Default Value: N/A
scope	Array of scope objects	Definition: Status of the service type supported by the resource pool. Constraints: N/A Range: N/A Default Value: N/A
driver	driver object	Definition: Resource pool driver status. Constraints: N/A Range: N/A Default Value: N/A
parent	String	Definition: ID of the parent resource pool to which a resource pool belongs. The physical pool is empty. Constraints: N/A Range: N/A Default Value: N/A
root	String	Definition: ID of the root resource pool. Constraints: N/A Range: N/A Default Value: N/A

**Table 24** resources
Parameter	Type	Description
creating	PoolResourceFlavorCount object	Definition: Resource information in creating states of the resource pool. Constraints: N/A Range: N/A Default Value: N/A
available	PoolResourceFlavorCount object	Definition: Resource information in available states of the resource pool. Constraints: N/A Range: N/A Default Value: N/A
abnormal	PoolResourceFlavorCount object	Definition: Resource information in abnormal states of the resource pool. Constraints: N/A Range: N/A Default Value: N/A
deleting	PoolResourceFlavorCount object	Definition: Resource information in deleting states of the resource pool. Constraints: N/A Range: N/A Default Value: N/A

**Table 25** PoolResourceFlavorCount
Parameter	Type	Description
flavor	String	Definition: Resource flavor ID. Constraints: N/A Range: N/A Default Value: N/A
count	Integer	Definition: Number of resource specification instances in a resource pool. Constraints: N/A Range: N/A Default Value: N/A
maxCount	Integer	Definition: Number of elastic resource specification instances in a resource pool. The value of this parameter in a physical pool is the same as that of count. Constraints: N/A Range: N/A Default Value: N/A
azs	Array of PoolNodeAz objects	Definition: AZ distribution of the resource specification instances to be created in a resource pool. Constraints: N/A Range: N/A Default Value: N/A
nodePool	String	Definition: Node pool ID. Constraints: N/A Range: N/A Default Value: N/A

**Table 26** PoolNodeAz
Parameter	Type	Description
az	String	Definition: AZ name. Constraints: N/A Range: N/A Default Value: N/A
count	Integer	Definition: Number of AZ resource instances. Constraints: N/A Range: N/A Default Value: N/A

**Table 27** scope
Parameter	Type	Description
scopeType	String	Definition: Service type of the resource pool. Constraints: N/A Range: Train: training jobs Infer: inference jobs Notebook: notebook jobs Default Value: N/A
state	String	Definition: Service type status of the resource pool. Constraints: N/A Range: Enabling: The service is being enabled. Enabled: The service has been enabled. Disabling: The service is being disabled. Disabled: The service has been disabled. Default Value: N/A

**Table 28** driver
Parameter	Type	Description
gpu	PoolDriverStatus object	Definition: GPU driver status of a resource pool. Constraints: N/A Range: N/A Default Value: N/A
npu	PoolDriverStatus object	Definition: NPU driver status of a resource pool. Constraints: N/A Range: N/A Default Value: N/A

**Table 29** PoolDriverStatus
Parameter	Type	Description
version	String	Definition: Current driver version of a resource pool. Constraints: N/A Range: N/A Default Value: N/A
state	String	Definition: Current driver status of a resource pool. Constraints: N/A Range: Creating: The driver is being installed. Upgrading: The driver is being upgraded. Running: The driver is running. Abnormal: The driver is abnormal. Default Value: N/A

Status code: 400

**Table 30** Response body parameters
Parameter	Type	Description
error_code	String	Definition: ModelArts error code. Range: N/A
error_msg	String	Definition: Error message. Range: N/A

Status code: 409

**Table 31** Response body parameters
Parameter	Type	Description
error_code	String	Definition: ModelArts error code. Range: N/A
error_msg	String	Definition: Error message. Range: N/A

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: Obtaining Resource Pools

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