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

Updated on 2025-11-19 GMT+08:00

View PDF

Creating Resource Pools

Function

This API is used to create a resource pool in the system. This API is used when you need to allocate resources for new services, optimize resource management, or isolate resources. You can use this API to create a resource pool to manage compute, storage, and network resources. Before using this API, ensure that you have the administrator permission and the system has sufficient resources to create resource pools. After the creation, the resource pool will be added to the system and be available for future resource allocation and management. If you do not have the required permission, the system resources are insufficient, or the input parameter is incorrect, the API will return an error message.

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	Definition: User project ID. For details, see Obtaining a Project ID and Name. Constraints: N/A Range: N/A Default Value: N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-ModelArts-User-ID	No	String	Definition: Tenant ID. If there is a tenant ID, it will be used for workspace authentication. Constraints: N/A Range: N/A Default Value: N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
apiVersion	Yes	String	Definition: API version. Constraints: N/A Range: v2 Default Value: N/A
kind	Yes	String	Definition: Resource type. Constraints: N/A Range: Pool: resource pool Default Value: N/A
metadata	Yes	PoolMetadataCreation object	Definition: Resource pool metadata. Constraints: N/A
spec	No	PoolSpecCreation object	Definition: Resource pool description. Constraints: N/A

**Table 4** PoolMetadataCreation
Parameter	Mandatory	Type	Description
labels	Yes	PoolLabelsCreation object	Definition: Tags of a resource pool. Constraints: N/A
annotations	No	PoolAnnotationsCreation object	Definition: Comments of a resource pool. Constraints: N/A

**Table 5** PoolLabelsCreation
Parameter	Mandatory	Type	Description
os.modelarts/name	Yes	String	Definition: Name of the resource pool specified by you. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/workspace.id	No	String	Definition: Workspace ID. [For details about how to obtain the ID, see Querying the Workspace List.] (tag:hc) Constraints: N/A Range: If no workspace is created, the default value is 0. If a workspace is created and used, use the actual value. Default Value: N/A
os.modelarts/node.prefix	No	String	Definition: Prefix of the node name. Constraints: N/A Range: N/A Default Value: N/A

**Table 6** PoolAnnotationsCreation
Parameter	Mandatory	Type	Description
os.modelarts/description	No	String	Definition: Resource pool description. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/billing.mode	No	String	Definition: Billing mode. Constraints: N/A Range: 0: pay-per-use 1: yearly/monthly Default Value: N/A
os.modelarts/period.num	No	String	Definition: Subscription period on a yearly/monthly basis, for example, 2. This parameter is mandatory when the billing mode is yearly/monthly. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/period.type	No	String	Definition: Subscription type on a yearly/monthly basis. This parameter is mandatory when the billing mode is yearly/monthly. Constraints: N/A Range: 2: month 3: year Default Value: N/A
os.modelarts/auto.renew	No	String	Definition: Specifies whether to automatically renew the subscription. Constraints: N/A Range: 0: auto-renewal disabled 1: auto-renewal enabled Default Value: 0
os.modelarts/auto.pay	No	String	Definition: Specifies whether to automatically pay for the subscription. This parameter is only valid when you purchase a yearly/monthly resource. Constraints: N/A Range: true: automatic payment false: manual payment (default value) Default Value: N/A
os.modelarts/promotion.info	No	String	Definition: Discount selected on CBC. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/service.console.url	No	String	Definition: URL of the page displayed after the subscription order is paid. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/order.id	No	String	Definition: Order ID, which is mandatory for creating a yearly/monthly resource pool or changing the billing mode. Constraints: N/A Range: N/A Default Value: N/A

**Table 7** PoolSpecCreation
Parameter	Mandatory	Type	Description
type	Yes	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	Yes	Array of strings	Definition: Job types supported by a resource pool. Constraints: N/A Range: Select at least one type when you create a standard resource pool. All options are supported by physical resource pools. Options: Train: training job Infer: inference job Notebook: notebook job Default Value: N/A
resources	Yes	Array of PoolResourceFlavor objects	Definition: Resource specifications in a resource pool, including resource specifications and the number of resources for each specification. Constraints: N/A
network	Yes	network object	Definition: Network parameters of a resource pool. This parameter is mandatory when you create a physical resource pool. Constraints: N/A
jobFlavors	No	Array of strings	Definition: Job specifications supported by a resource pool, which are specified by the job specification name Constraints: N/A
driver	No	PoolDriver object	Definition: Resource pool driver information. Constraints: N/A

**Table 8** PoolResourceFlavor
Parameter	Mandatory	Type	Description
flavor	Yes	String	Definition: Resource flavor, for example, modelarts.vm.gpu.tnt004. Constraints: N/A Range: N/A Default Value: N/A
count	Yes	Integer	Definition: Committed resources of the flavor. Constraints: N/A Range: N/A Default Value: N/A
maxCount	No	Integer	Definition: Elastic resources of the flavor. The value must be the same as that of count in the physical pool. Constraints: N/A Range: N/A Default Value: N/A
extendParams	No	extendParams object	Definition: Custom configuration parameters. Constraints: N/A
os	No	Os object	Definition: Custom OS image information. Constraints: N/A

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

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

**Table 11** network
Parameter	Mandatory	Type	Description
name	No	String	Definition: Network name, which is the value of metadata.name in the network details. When you create a network with a specified name, the system will automatically create subnets for you. By default, the first subnet will be used. Constraints: N/A Range: N/A Default Value: N/A

**Table 12** PoolDriver
Parameter	Mandatory	Type	Description
gpuVersion	No	String	Definition: Default GPU driver version of a resource pool. This parameter is only valid when the physical resource pool contains GPU specifications. Range: N/A
npuVersion	No	String	Definition: Default NPU driver version of a resource pool. This parameter is only valid when the physical resource pool contains NPU specifications. Range: N/A
updateStrategy	No	String	Definition: Driver upgrade policy of a resource pool. 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.

Response Parameters

Status code: 200

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

**Table 14** PoolMetadata
Parameter	Type	Description
name	String	Definition: Resource pool ID. Range: N/A
creationTimestamp	String	Definition: Time when a resource pool is created. For example, 2025-11-01T03:49:41Z. Range: N/A
labels	PoolMetaLabels object	Definition: Tags of a resource pool.
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/name	String	Definition: Displayed name of a resource pool. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/workspace.id	String	Definition: Workspace ID. [For details about how to obtain the ID, see Querying the Workspace List.] (tag:hc,hk) Constraints: N/A Range: N/A Default Value: 0
os.modelarts/node.prefix	String	Definition: Custom node prefix. This parameter is optional. 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
os.modelarts/tenant.project.id	String	Definition: ID of the tenant project that a resource pool belongs to. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/enterprise.project.id	String	Definition: ID of the enterprise project that a resource pool belongs to. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts.pool/biz	String	Definition: Business type of a resource pool. The value can be public or private. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/create-from	String	Definition: Source of a resource pool, for example, admin-console, indicating that the resource pool is created by the administrator on the ModelArts console. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/nobilling	String	Definition: Indicates whether the resource pool is charged. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/order.name	String	Definition: Last order job record associated with the resource pool. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/region	String	Definition: Region where the resource pool is located. 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
os.modelarts.pool/scheduler.queue.strategy	String	Definition: Policy of the resource pool scheduling queue, which is used to define task scheduling rules. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts.pool/subpools.count	String	Definition: Number of logical subpools in a resource pool. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts/tenant.domain.name	String	Definition: Tenant account of the resource pool. Constraints: N/A Range: N/A Default Value: N/A
os.modelarts.pool/scope.external.dependency.train	String	Definition: External dependency ID of the training job. 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.
resources	Array of resources objects	Definition: Resource specifications in a resource pool, including resource specifications and the number of resources for each specification.
containernetwork	containernetwork object	Kubernetes container network.
network	network object	Definition: Network parameters of a resource pool.
jobFlavors	Array of strings	Definition: Job specifications supported by a resource pool. The value is the job specification name.
driver	PoolDriver object	Definition: Resource pool driver information.
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. Range: 0: not restricted 1: Changing to the yearly/monthly billing is restricted. 2: Modifying specifications is restricted. 4: The service is restricted. 8: The resource pool is frozen. 16: The resource pool is frozen by the public security department (cannot be unsubscribed).

**Table 18** resources
Parameter	Type	Description
flavor	String	Definition: Resource flavor ID. Range: N/A
count	Integer	Definition: Number of resource specification instances in a resource pool. Range: N/A
maxCount	Integer	Elastic resource amount of the resource specifications. The value must be the same as that of count in the physical pool.
azs	Array of PoolNodeAz objects	Definition: AZ distribution of the resource specification instances to be created in a resource pool.
extendParams	extendParams object	Definition: Custom parameters of a resource pool.
os	Os object	Definition: OS image information of nodes in a resource pool.
dataVolumes	dataVolumes object	List of custom cloud data disks. The list cannot be modified after being specified.
volumeGroupConfigs	volumeGroupConfigs object	Advanced disk configurations.

**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
volumeGroup	String	Disk group name.
runtime	String	Model runtime environment.

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

**Table 21** dataVolumes
Parameter	Type	Description
volumeType	String	Disk type.. Options: SSD: ultra-high I/O disk GPSSD: general-purpose SSD SAS: high I/O disk
size	String	Disk size, in GiB.
count	String	Number of disks.
extendParams	extendParams object	Custom disk configuration.

**Table 22** extendParams
Parameter	Type	Description
billing	String	Indicates whether the storage instance is billed. If this parameter is left blank, the storage instance is not billed. This field cannot be specified or modified by users.
volumeGroup	String	Name of a disk group, which is used to divide storage space. Options: vgpaas: container disk. default: common data disk, which is mounted in default mode. vguser{num}: common data disk, which is mounted to a specified path. The group name varies depending on the path, for example, vguser1 and vguser2. vg-everest-localvolume-persistent: common data disk, which is used as the persistent storage volume. vg-everest-localvolume-ephemeral: common data disk, which is used as a temporary storage volume.

**Table 23** volumeGroupConfigs
Parameter	Type	Description
volumeGroup	String	Disk group name. Index of the volume group in the dataVolumes.
dockerThinPool	String	Percentage of container disks to data disks on nodes in a resource pool. This parameter can be specified only when volumeGroup is vgpaas (container disk).
lvmConfig	lvmConfig object	LVM configuration management.

**Table 24** lvmConfig
Parameter	Type	Description
lvType	String	LVM write mode. Options: linear: linear mode. striped: striped mode in which multiple disks are used to form a strip to improve disk performance.

**Table 25** containernetwork
Parameter	Type	Description
mode	String	Container network model. Options: overlay_l2: an overlay_l2 network (container tunnel network) built for containers by using OpenVSwitch (OVS). vpc-router: an underlay_l2 network built for containers by using IPvlan and custom VPC routes. eni: Cloud Native Network 2.0. This model deeply integrates the native ENI capability of VPC, uses the VPC CIDR block to allocate container addresses, and supports passthrough networking. You can use this model when creating a CCE Turbo cluster.

**Table 26** network
Parameter	Type	Description
name	String	Definition: Network ID. Range: N/A

**Table 27** PoolDriver
Parameter	Type	Description
gpuVersion	String	Definition: Default GPU driver version of a resource pool. This parameter is only valid when the physical resource pool contains GPU specifications. Range: N/A
npuVersion	String	Definition: Default NPU driver version of a resource pool. This parameter is only valid when the physical resource pool contains NPU specifications. Range: N/A
updateStrategy	String	Definition: Driver upgrade policy of a resource pool. 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.

**Table 28** PoolStatus
Parameter	Type	Description
phase	String	Definition: Resource pool status. 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.
message	String	Definition: Prompt information about the resource pool status. Range: N/A
resources	resources object	Definition: Resource information in different states of the resource pool.
scope	Array of scope objects	Definition: Status of the service type supported by the resource pool.
driver	driver object	Definition: Resource pool driver status.
parent	String	Definition: ID of the parent resource pool to which a resource pool belongs. The physical pool is empty. Range: N/A
root	String	Definition: ID of the root resource pool. Range: N/A
clusters	clusters object	Resource pool cluster information. This parameter is available only for privileged pools.

**Table 29** resources
Parameter	Type	Description
creating	PoolResourceFlavorCount object	Definition: Resource information in creating states of the resource pool.
available	PoolResourceFlavorCount object	Definition: Resource information in available states of the resource pool.
abnormal	PoolResourceFlavorCount object	Definition: Resource information in abnormal states of the resource pool.
deleting	PoolResourceFlavorCount object	Definition: Resource information in deleting states of the resource pool.

**Table 30** PoolResourceFlavorCount
Parameter	Type	Description
flavor	String	Definition: Resource flavor ID. Range: N/A
count	Integer	Definition: Number of resource specification instances in a resource pool. Range: 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. Range: N/A
azs	Array of PoolNodeAz objects	Definition: AZ distribution of the resource specification instances to be created in a resource pool.
nodePool	String	Definition: Node pool ID. Range: N/A

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

**Table 32** scope
Parameter	Type	Description
scopeType	String	Definition: Service type of the resource pool. Range: Train: training jobs Infer: inference jobs Notebook: notebook jobs
state	String	Definition: Service type status of the resource pool. 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.

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

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

**Table 35** clusters
Parameter	Type	Description
name	String	Cluster name.
clusterFlavor	String	Cluster flavor of a standard pool.
type	String	Type of the resource pool cluster.
version	String	Cluster version.
plugins	plugins object	Name of the plugin supported by the cluster.

**Table 36** plugins
Parameter	Type	Description
name	String	Name of the plugin supported by the cluster.

Status code: 400

**Table 37** 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 38** 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