Updated on 2025-08-20 GMT+08:00

Creating Resource Pools

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.