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 source.

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/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/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. Logical: logical resource pool. After a logical pool is created, contact the administrator for 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) Enumeration values: Train Infer Notebook
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.
extendParams	No	Map<String,String>	Custom configuration, for example, setting dockerSize to "extendParams": {"dockerBaseSize": "100" }
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:
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/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	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. Logical: logical resource pool. After a logical pool is created, contact the administrator for 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) Enumeration values: Train Infer Notebook
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. 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.

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.
extendParams	Map<String,String>	Custom configuration, for example, setting dockerSize to "extendParams": {"dockerBaseSize": "100" }
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 Enumeration values: overlay_l2 vpc-router eni
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 [- Notebook: notebook jobs](tags: hc) Enumeration values: Train Infer Notebook
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"
      },
      "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.

last updated: 2024-12-11 13:55 UTC - commit: afb4a7dfa15e256dc933e946d9e874db041cb35c