Updated on 2024-06-13 GMT+08:00

Creating Resource Pools

Function

This API is used to create resource pools.

URI

POST /v2/{project_id}/pools

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

request-type

No

String

Request type.

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/workspace.id

No

String

Workspace ID. The default value is 0.

Default: 0

os.modelarts/name

Yes

String

Specified resource pool name

Minimum: 4

Maximum: 64

os.modelarts/sharing

No

String

Whether the resource pool can be shared. The value can be unshared or shared.

os.modelarts/node.prefix

No

String

Customized node prefix. This parameter is optional.

Table 6 PoolAnnotationsCreation

Parameter

Mandatory

Type

Description

os.modelarts/description

No

String

Description of a resource pool

os.modelarts/billing.mode

No

String

Billing mode. Options:

  • 0: pay-per-use

os.modelarts/period.num

No

String

Subscription period on a yearly/monthly basis, 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. Options:

  • 2: month

  • 3: year

  • 4: hour

This parameter is mandatory when Billing Mode is set to Yearly/Monthly.

os.modelarts/auto.renew

No

String

Whether to automatically renew the subscription. Options:

  • 0: auto-renewal disabled (default value)

  • 1: auto-renewal enabled

os.modelarts/promotion.info

No

String

Discount selected on the operations platform

os.modelarts/service.console.url

No

String

URL of the page displayed after the subscription order is paid

os.modelarts/order.id

No

String

Order ID, which is mandatory for creating a yearly/monthly resource pool or changing the billing mode

os.modelarts/scheduler.extension

No

String

Priority that can be set for the jobs delivered by other users to the shared resource pool

Table 7 PoolSpecCreation

Parameter

Mandatory

Type

Description

type

Yes

object

Resource pool type.

  • Dedicate: physical resource pool, which uses a separate network and supports network connection, custom drivers, and custom job types.

  • Logical: logical resource pool, which can be used after the administrator's approval.

scope

No

Array of strings

Job type enabled, which cannot be specified for logical pools. Options:

  • Train: training jobs

  • Infer: inference jobs [- Notebook: notebook jobs](tags: hc)

resources

Yes

Array of PoolResourceFlavorCount objects

Resource specifications in a resource pool, including resource specifications and the number of resources for each specification

parent

No

String

Parent resource pool ID. This parameter is mandatory when a logical sub-pool is created based on a specified resource pool.

network

No

PoolNetwork object

Network settings for a resource pool. This parameter is mandatory for creating physical resource pools and is unavailable for creating logical resource pools.

containerNetwork

No

containerNetwork object

Kubernetes container network segment. Only one container network segment is supported. This parameter is optional. If this parameter is not set, the default value is specified by CCE.

kubernetesSvcIpRange

No

String

CIDR of the Kubernetes service network segment

masters

No

Array of PoolClusterMaster objects

Master node parameters in a resource pool. This parameter is optional for physical resource pools and is unavailable for logical resource pools.

driver

No

PoolDriver object

Resource pool driver

userLogin

No

PoolUserLogin object

Node login information of a privilege pool

clusters

No

Array of PoolClusterInfo objects

Privilege pool cluster information

ipv6enable

No

Boolean

Whether to enable IPv6

Table 8 PoolResourceFlavorCount

Parameter

Mandatory

Type

Description

flavor

Yes

String

Resource specifications name, for example, modelarts.vm.gpu.t4u8

count

Yes

Integer

Minimum count for the specifications in a resource pool

maxCount

Yes

Integer

Elastic usage of the resource specifications. This parameter value is the same the count value in a physical pool; It is greater than or equal to the count value in a logical pool.

azs

No

Array of PoolNodeAz objects

AZ where resource pool nodes are deployed.

Table 9 PoolNodeAz

Parameter

Mandatory

Type

Description

az

Yes

String

AZ name.

count

Yes

Integer

Number of nodes for expanding the capacity of a specified AZ.

Minimum: 1

Maximum: 2000

Table 10 PoolNetwork

Parameter

Mandatory

Type

Description

name

No

String

Network name. 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.

Minimum: 4

Maximum: 128

vpcId

No

String

VPC ID, which must be specified when a privileged pool is created and is unavailable for a non-privileged pool

subnetId

No

String

Subnet ID, which must be specified when a privileged pool is created and is unavailable for a non-privileged pool

Table 11 containerNetwork

Parameter

Mandatory

Type

Description

cidr

No

String

CIDR block of the container network segment. Recommended: 10.0.0.0/12-19, 172.16.0.0/16-19, or 192.168.0.0/16-19. If the selected CIDR block conflicts with existing ones, an error will be reported. This parameter cannot be modified after the cluster is created.

Table 12 PoolClusterMaster

Parameter

Mandatory

Type

Description

az

No

String

AZ where the master node is located

Table 13 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 available when Ascend chips are used in a physical resource pool. For example, the Ascend driver version is C78.

updateStrategy

No

String

Driver upgrade policy. Options:

  • 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 14 PoolUserLogin

Parameter

Mandatory

Type

Description

keyPairName

No

String

Key pair name

password

No

String

Password, which must be salted, encrypted, and encoded using Base64. The default username is root.

Table 15 PoolClusterInfo

Parameter

Mandatory

Type

Description

name

No

String

Cluster name

providerId

No

String

Cluster ID

Response Parameters

Status code: 200

Table 16 Response body parameters

Parameter

Type

Description

apiVersion

String

API version. Options:

  • v2

kind

String

Resource type. Options:

  • Pool: resource pool

metadata

PoolMetadata object

Metadata of a resource pool.

spec

PoolSpec object

Description of a resource pool.

status

PoolStatus object

Status of a resource pool.

Table 17 PoolMetadata

Parameter

Type

Description

name

String

Automatically generated resource pool name, which is equivalent to pool ID.

Minimum: 4

Maximum: 128

creationTimestamp

String

Timestamp, for example, 2021-11-01T03:49:41Z.

labels

PoolMetaLabels object

Resource pool labels.

annotations

PoolMetaAnnotations object

Resource pool annotations.

Table 18 PoolMetaLabels

Parameter

Type

Description

os.modelarts/workspace.id

String

Workspace ID.

Default: 0

os.modelarts/name

String

Specified resource pool name.

Minimum: 4

Maximum: 64

os.modelarts/resource.id

String

Resource ID, which is typically 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

os.modelarts/create-from

String

Source of a resource pool, for example, admin-console, indicating that the resource pool is created by the administrator on the ModelArts console

os.modelarts.pool/biz

String

Business type of a resource pool. The value can be public or private.

os.modelarts/privileged

String

Whether a resource pool is a privileged pool. If this parameter is specified, the resource pool is a privileged one.

os.modelarts/sharing

String

Whether the resource pool can be shared. Options:

  • unshared: It cannot be shared.

  • shared: It can be shared.

Table 19 PoolMetaAnnotations

Parameter

Type

Description

os.modelarts/description

String

Description of a resource pool.

os.modelarts/billing.mode

String

Billing mode. Options:

  • 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. Options:

  • 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

Resource ID corresponding to each specification, which is used for interaction with the operations platform

os.modelarts/tms.tags

String

Resource tags specified by the user during creation

os.modelarts/scheduler.extension

String

Priority that can be set for the jobs delivered by other users to the shared resource pool

os.modelarts.pool/subpools.count

String

Number of logical sub-pools in a resource pool

Table 20 PoolSpec

Parameter

Type

Description

type

object

Resource pool type.

  • Dedicate: physical resource pool, which uses a separate network and supports network connection, custom drivers, and custom job types.

  • Logical: logical resource pool, which can be used after the administrator's approval.

scope

Array of strings

Job type enabled, which cannot be specified for logical pools. Options:

  • Train: training jobs

  • Infer: inference jobs [- Notebook: notebook jobs](tags: hc)

resources

Array of PoolResourceFlavorCount objects

Resource specifications in a resource pool, including resource specifications and the number of resources for each specification.

network

PoolNetwork object

Network settings for a resource pool. This parameter is mandatory for physical resource pools and is unavailable for logical resource pools.

containerNetwork

PoolClusterContainerNetwork object

Kubernetes container network

kubernetesSvcIpRange

String

CIDR of the Kubernetes service network segment

masters

Array of PoolClusterMaster objects

Master node parameters in a resource pool. This parameter is optional for physical resource pools and is unavailable for logical resource pools.

driver

PoolDriver object

Resource pool driver.

userLogin

PoolUserLogin object

Node login information of a privilege pool

clusters

Array of PoolClusterInfo objects

Privilege pool cluster information

ipv6enable

Boolean

Whether to enable IPv6

controlMode

Integer

Restriction status of a resource pool. Options:

  • 0: The resource pool is not restricted.

  • 1: Changing to 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). 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 21 PoolResourceFlavorCount

Parameter

Type

Description

flavor

String

Resource specifications name, for example, modelarts.vm.gpu.t4u8

count

Integer

Minimum count for the specifications in a resource pool

maxCount

Integer

Elastic usage of the resource specifications. This parameter value is the same the count value in a physical pool; It is greater than or equal to the count value in a logical pool.

azs

Array of PoolNodeAz objects

AZ where resource pool nodes are deployed.

Table 22 PoolNetwork

Parameter

Type

Description

name

String

Network name. 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.

Minimum: 4

Maximum: 128

vpcId

String

VPC ID, which must be specified when a privileged pool is created and is unavailable for a non-privileged pool

subnetId

String

Subnet ID, which must be specified when a privileged pool is created and is unavailable for a non-privileged pool

Table 23 PoolClusterContainerNetwork

Parameter

Type

Description

mode

String

Container network model

cidr

String

Container network segment. This parameter is available only when the container network model is overlay_l2 or vpc-router.

Table 24 PoolClusterMaster

Parameter

Type

Description

az

String

AZ where the master node is located

Table 25 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 available when Ascend chips are used in a physical resource pool. For example, the Ascend driver version is C78.

updateStrategy

String

Driver upgrade policy. Options:

  • 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 26 PoolUserLogin

Parameter

Type

Description

keyPairName

String

Key pair name

password

String

Password, which must be salted, encrypted, and encoded using Base64. The default username is root.

Table 27 PoolStatus

Parameter

Type

Description

phase

String

Resource pool status. Options:

  • Creating: The resource pool is being created.

  • Running: The resource pool is running.

  • Abnormal: The resource pool malfunctions.

  • Deleting: The resource pool is being deleted.

  • Error: An error occurred in the resource pool.

  • CreationFailed: Creating the resource pool failed.

  • ScalingFailed: Expanding the capacity of the resource pool failed.

  • Waiting: The resource pool is awaiting creation, which is typically caused by an unpaid order or unapproved request.

message

String

Message indicating that the resource pool is in the current state.

resources

resources object

Left blank for logical pools, which do not need to be created.

scope

Array of scope objects

Service status of a resource pool.

driver

driver object

Resource pool driver.

parent

String

Name of the parent node of a resource pool. This parameter is left blank for physical pools.

root

String

Name of the root node in a resource pool. For a physical pool, the value is its name.

clusters

Array of PoolClusterInfo objects

Resource pool cluster information. This parameter is available only for privileged pools.

Table 28 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 29 PoolNodeAz

Parameter

Type

Description

az

String

AZ name.

count

Integer

Number of nodes for expanding the capacity of a specified AZ.

Minimum: 1

Maximum: 2000

Table 30 scope

Parameter

Type

Description

scopeType

String

Job type enabled, which cannot be specified for logical pools. Options:

  • Train: training jobs

  • Infer: inference jobs

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 31 driver

Parameter

Type

Description

gpu

PoolDriverStatus object

GPU driver.

npu

PoolDriverStatus object

NPU driver.

Table 32 PoolDriverStatus

Parameter

Type

Description

version

String

Driver version

state

String

Driver status. Options:

  • Creating: The driver is being created.

  • Upgrading: The driver is being upgraded.

  • Running: The driver is running.

  • Abnormal: The driver malfunctions.

Table 33 PoolClusterInfo

Parameter

Type

Description

name

String

Cluster name

providerId

String

Cluster ID

Status code: 400

Table 34 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 409

Table 35 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Requests

  • Create a physical pool.

    POST https://{endpoint}/v2/{project_id}/pools
    
    {
      "kind" : "Pool",
      "apiVersion" : "v1",
      "metadata" : {
        "labels" : {
          "os.modelarts/name" : "pool-001",
          "os.modelarts/workspace.id" : "xxxxxx"
        },
        "annotations" : {
          "os.modelarts/description" : "",
          "os.modelarts/billing.mode" : "0"
        }
      },
      "spec" : {
        "type" : "Dedicate",
        "scope" : [ "Train" ],
        "network" : {
          "name" : "net-01"
        },
        "masters" : [ {
          "az" : "xxxxxx-7a"
        } ],
        "resources" : [ {
          "flavor" : "modelarts.vm.gpu.t4u8",
          "count" : 2
        } ],
        "driver" : {
          "gpuVersion" : "440.31"
        }
      }
    }
  • Create a logical pool.

    POST https://{endpoint}/v2/{project_id}/pools
    
    {
      "kind" : "Pool",
      "apiVersion" : "v1",
      "metadata" : {
        "labels" : {
          "os.modelarts/name" : "pool-logic-01"
        },
        "annotations" : {
          "os.modelarts/description" : "",
          "os.modelarts/billing.mode" : 0,
          "os.modelarts/product.id" : "xxx"
        }
      },
      "spec" : {
        "type" : "Logical",
        "scope" : [ "Train" ],
        "resources" : [ {
          "flavor" : "modelarts.vm.gpu.t4u8",
          "count" : 2
        } ]
      }
    }

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.