Creating a Resource Pool

Function

This API is used to create a resource pool.

Debugging

You can debug this API in which supports automatic authentication. API Explorer automatically generates sample SDK code and provides the debug function.

URI

POST /v2/{project_id}/pools

Table 1 URI 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.
request-type	No	String	Request source. The order function of CBC is enabled only when console is set.

Table 3 Request body parameters

Parameter	Mandatory	Type	Description
apiVersion	Yes	String	API version. The options are as follows: v2
kind	Yes	String	Resource type. The options are as follows: Pool: resource pool
metadata	Yes	PoolMetadataCreation object	Resource pool metadata.
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.
os.modelarts/name	Yes	String	Specified resource pool name.
os.modelarts/sharing	No	String	Whether the resource pool can be shared. The value can be unshared or shared.

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. The options are as follows: 0: pay-per-use billing mode
os.modelarts/period.num	No	String	Subscription period, for example, 2.
os.modelarts/period.type	No	String	Subscription type. The options are as follows: 2: monthly 3: yearly 4: hourly
os.modelarts/auto.renew	No	String	Whether to enable auto-renewal. The options are as follows: 0: auto-renewal disabled (default value) 1: auto-renewal enabled
os.modelarts/promotion.info	No	String	Discount selected by a user.
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.
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	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. Select at least one job type. The options are as follows: Train: training job Infer: inference job
resources	Yes	Array of PoolResourceFlavor objects	Resource flavor list in a resource pool, including resource flavors and the number of resources for each flavor.
parent	No	String	ID of the parent resource pool. This parameter is mandatory when a logical sub-pool is created based on a specified resource pool.
network	No	network object	Network settings for a resource pool. This parameter is mandatory for creating physical resource pools and is unavailable for creating logical resource pools.
masters	No	Array of masters objects	Master node parameters in a resource pool. This parameter is optional for physical resource pools and is unavailable for logical resource pools.
jobFlavors	No	Array of strings	Names of the job flavors supported by a resource pool.
driver	No	PoolDriver object	Resource pool driver information.

Table 8 PoolResourceFlavor

Parameter	Mandatory	Type	Description
flavor	Yes	String	Resource flavor, for example, modelarts.vm.gpu.t4u8
count	Yes	String	Number of resources of the specified flavor

Table 9 network

Parameter	Mandatory	Type	Description
name	Yes	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.

Table 10 masters

Parameter	Mandatory	Type	Description
az	No	String	AZ where the master node is located

Table 11 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. The options are as follows: 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 12 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	Resource pool metadata.
spec	PoolSpec object	Expected resource pool specifications.
status	PoolStatus object	Resource pool status.

Table 13 PoolMetadata

Parameter	Type	Description
name	String	Automatically generated resource pool name, which is equivalent to the 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 14 PoolMetaLabels

Parameter	Type	Description
os.modelarts/workspace.id	String	Workspace ID.
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.
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/sharing	String	Whether the resource pool can be shared. The options are as follows: unshared: It cannot be shared. shared: It can be shared.

Table 15 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 billing mode
os.modelarts/period.num	String	Subscription period, for example, 2.
os.modelarts/period.type	String	Subscription type. The options are as follows: 2: monthly 3: yearly 4: hourly
os.modelarts/auto.renew	String	Whether to enable auto-renewal. The options are as follows: 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.
os.modelarts/flavor.resource.ids	String	Resource ID corresponding to each flavor, which is used for interaction with CBC.
os.modelarts/tms.tags	String	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 16 PoolSpec

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 a resource pool. Select at least one type. All options are supported by physical resource pools. Logical resource pools support only training jobs. The options are as follows: Train: training job Infer: inference job
resources	Array of resources objects	Resource flavor list in a resource pool, including resource flavors and the number of resources for each flavor.
network	network object	Network settings for a resource pool. This parameter is mandatory for physical resource pools and is unavailable for logical resource pools.
masters	Array of masters objects	Master node parameters in a resource pool. This parameter is optional for physical resource pools and is unavailable for logical resource pools.
jobFlavors	Array of strings	Names of the job flavors supported by a resource pool.
driver	PoolDriver object	Resource pool driver information.
controlMode	Integer	Restriction status of a resource pool. The options are as follows: 0: It is not restricted. 2: Modifying specifications is restricted. 4: The service is restricted. 8: It is frozen. A resource pool can have several statuses.

Table 17 resources

Parameter	Type	Description
flavor	String	Resource flavor, for example, modelarts.vm.gpu.t4u8
count	Integer	Number of resources of the specified flavor
azs	Array of PoolNodeAz objects	AZ list

Table 18 PoolNodeAz

Parameter	Type	Description
az	String	AZ name
count	Integer	Number of nodes for expanding the capacity of a specified AZ

Table 19 network

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.

Table 20 masters

Parameter	Type	Description
az	String	AZ where the master node is located

Table 21 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. The options are as follows: 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 22 PoolStatus

Parameter	Type	Description
phase	String	Status of a resource pool. The options are as follows: Creating: It is being created. Running: It is running. Abnormal: It malfunctions. Deleting: It is being deleted. Error: An error occurred in the resource pool. CreationFailed: It fails to be created. ScalingFailed: It fails to be scaled out. Waiting: It 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	Resources in different states in a resource pool.
scope	Array of scope objects	Service status in the resource pool.
driver	driver object	Resource pool driver information.
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.

Table 23 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 abnormal resources
deleting	PoolResourceFlavorCount object	Number of resources that are being deleted

Table 24 PoolResourceFlavorCount

Parameter	Type	Description
flavor	String	Resource flavor name, for example, modelarts.vm.gpu.t4u8.
count	Integer	Minimum count for the flavors in a resource pool.
maxCount	Integer	Elastic usage of the resource flavor. 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 azs objects	Number of AZs where resources are located.

Table 25 azs

Parameter	Type	Description
az	String	AZ name
count	Integer	Number of AZ resources

Table 26 scope

Parameter	Type	Description
scopeType	String	Service type. The options are as follows: Train: training job Infer: inference job
state	String	Service status. The options are as follows: Enabling: It is being started. Enabled: It is enabled. Disabling: It is being disabled. Disabled: It is disabled.

Table 27 driver

Parameter	Type	Description
gpu	PoolDriverStatus object	GPU driver information
npu	PoolDriverStatus object	NPU driver information

Table 28 PoolDriverStatus

Parameter	Type	Description
version	String	Current driver version.
state	String	Current driver status. The options are as follows: Creating: It is being created. Upgrading: It is being upgraded. Running: It is running. Abnormal: It is abnormal.

Status code: 400

Table 29 Response body parameters

Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error message

Status code: 409

Table 30 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" : "xxxxx-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
      } ],
      "jobFlavors" : [ "modelarts.job.vm.2u" ]
    }
  }
  

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

For details, see Error Codes.

last updated: 2024-09-07 00:04