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. For details, see Obtaining a Project ID and Name.

Request Parameters¶

**Table 2** Request header parameters¶
Parameter	Mandatory	Type	Description
request-type	No	String	Request source. The order function is enabled only when console is set.

**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.
os.modelarts/name	Yes	String	Specified resource pool name. The value contains 4 to 25 characters, including lowercase letters, hyphens (-), and digits.
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
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	No	Array of strings	Job type enabled. Options: Train: training jobs Infer: inference jobs [- Notebook: notebook jobs](tags: hc)
resources	Yes	Array of PoolResource 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.
network	No	PoolNetwork object	Network settings for a resource pool. This parameter is mandatory for creating physical resource pools.
containerNetwork	No	PoolContainerNetwork 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.
clusterFlavor	No	String	Cluster flavor of a standard pool.
driver	No	PoolDriver object	Resource pool driver
ipv6enable	No	Boolean	Whether to enable IPv6

**Table 8** PoolResource¶
Parameter	Mandatory	Type	Description
flavor	Yes	String	Resource flavor name, for example, modelarts.vm.gpu.tnt004.
count	Yes	Integer	Minimum count for the flavors in a resource pool.
maxCount	No	Integer	Elastic usage of the resource flavor. This parameter value is the same the count value in a physical pool.
azs	No	Array of PoolNodeAz objects	AZ where resource pool nodes are deployed.
tags	No	Array of UserTag objects	Resource tags.
extendParams	No	PoolResourceExtendParams object	Custom configuration, for example, setting dockerSize for the node.
creatingStep	No	CreatingStep object	Batch creation information.
rootVolume	No	RootVolume object	Custom system disk (cloud hard disk) information.
dataVolumes	No	Array of DataVolumeItem objects	List of custom data disks (cloud hard disks).
volumeGroupConfigs	No	Array of VolumeGroupConfig objects	Advanced disk configurations. This parameter is mandatory when a custom data disk exists.

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

**Table 10** UserTag¶
Parameter	Mandatory	Type	Description
key	Yes	String	Key. The value cannot start with CCE- or __type_baremetal.
value	Yes	String	Value.

**Table 11** PoolResourceExtendParams¶
Parameter	Mandatory	Type	Description
dockerBaseSize	No	String	Size of the container image space on a node.
postInstall	No	String	Post-installation script. The entered value must be encoded using Base64.

**Table 12** CreatingStep¶
Parameter	Mandatory	Type	Description
step	No	Integer	Creation step.
type	No	String	Batch creation type. rack: entire rack hyperinstance: supernodes

**Table 13** RootVolume¶
Parameter	Mandatory	Type	Description
volumeType	Yes	String	Disk type. The options are as follows: SSD: ultra-high I/O disk GPSSD: general-purpose SSD SAS: high I/O disk
size	Yes	String	Disk size, in GiB.

**Table 14** DataVolumeItem¶
Parameter	Mandatory	Type	Description
volumeType	Yes	String	Disk type. The options are as follows: SSD: ultra-high I/O disk GPSSD: general-purpose SSD SAS: high I/O disk
size	Yes	String	Disk size, in GiB.
count	No	Integer	Number of disks.
extendParams	Yes	VolumeExtendParams object	Custom disk configuration.

**Table 15** VolumeExtendParams¶
Parameter	Mandatory	Type	Description
volumeGroup	Yes	String	Name of a disk group, which is used to divide storage space. The options are as follows: 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 16** VolumeGroupConfig¶
Parameter	Mandatory	Type	Description
volumeGroup	Yes	String	Disk group name. Index of the volume group in the dataVolumes.
dockerThinPool	No	Integer	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	No	LvmConfig object	LVM configuration management.
types	No	Array of strings	Storage type. The options are as follows: volume: cloud hard disk. When dataVolumes is specified, the default value is used. local: local disk. This parameter must be specified when a local disk is used.

**Table 17** LvmConfig¶
Parameter	Mandatory	Type	Description
lvType	Yes	String	LVM write mode. The options are as follows: linear: linear mode. striped: striped mode in which multiple disks are used to form a strip to improve disk performance.
path	No	String	Disk mount path. This parameter takes effect only in user configuration. The value is an absolute path. Digits, letters, periods (.), hyphens (-), and underscores (_) are allowed.

**Table 18** PoolNetwork¶
Parameter	Mandatory	Type	Description
name	No	String	Network name. The value is obtained from the metadata.name field in the network resource details.

**Table 19** PoolContainerNetwork¶
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 20** PoolClusterMaster¶
Parameter	Mandatory	Type	Description
az	No	String	AZ where the master node is located

**Table 21** 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.
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.

Response Parameters¶

Status code: 200

**Table 22** 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 23** PoolMetadata¶
Parameter	Type	Description
name	String	Automatically generated resource pool name, which is equivalent to 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 24** PoolMetaLabels¶
Parameter	Type	Description
os.modelarts/workspace.id	String	Workspace ID
os.modelarts/name	String	Resource pool name specified by the user.
os.modelarts/resource.id	String	Resource ID of the resource pool.
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. Options: unshared: It cannot be shared. shared: It can be shared.

**Table 25** PoolMetaAnnotations¶
Parameter	Type	Description
os.modelarts/description	String	Description of a resource pool.
os.modelarts/billing.mode	String	Billing mode.
os.modelarts/flavor.resource.ids	String	Resource ID corresponding to each flavor.
os.modelarts/tms.tags	String	Resource tags specified by the user during resource pool 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/volcano.scheduler.cabinet-exclusive.enabled	String	Whether a resource pool that is not provisioned for an entire cabinet can deliver the job of an entire cabinet. If this annotation exists, the resource pool can deliver such a job. By default, a resource pool provisioned for an entire cabinet (that is, creatingStep resources of the rack type) supports this function.
os.modelarts.pool/scope.external.dependency.Train	String	External dependency ID of training.
os.modelarts.pool/scope.external.dependency.Infer	String	External dependency ID of inference.
os.modelarts.pool/scope.external.dependency.Notebook	String	External dependency ID of the development environment.

**Table 26** 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 enabled. Options: Train: training jobs Infer: inference jobs [- Notebook: notebook jobs](tags: hc)
resources	Array of PoolResource objects	Resource flavor list in a resource pool, including resource flavors, the number of resources for each flavor, and node pool information.
network	PoolNetwork object	Network settings for a resource pool. This parameter is mandatory for physical 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.
clusterFlavor	String	Cluster flavor of a standard pool.
driver	PoolDriver object	Resource pool driver.

**Table 27** PoolResource¶
Parameter	Type	Description
flavor	String	Resource flavor name, for example, modelarts.vm.gpu.tnt004.
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.
azs	Array of PoolNodeAz objects	AZ where resource pool nodes are deployed.
tags	Array of UserTag objects	Resource tags.
extendParams	PoolResourceExtendParams object	Custom configuration, for example, setting dockerSize for the node.
creatingStep	CreatingStep object	Batch creation information.
rootVolume	RootVolume object	Custom system disk (cloud hard disk) information.
dataVolumes	Array of DataVolumeItem objects	List of custom data disks (cloud hard disks).
volumeGroupConfigs	Array of VolumeGroupConfig objects	Advanced disk configurations. This parameter is mandatory when a custom data disk exists.

**Table 28** UserTag¶
Parameter	Type	Description
key	String	Key. The value cannot start with CCE- or __type_baremetal.
value	String	Value.

**Table 29** PoolResourceExtendParams¶
Parameter	Type	Description
dockerBaseSize	String	Size of the container image space on a node.
postInstall	String	Post-installation script. The entered value must be encoded using Base64.

**Table 30** RootVolume¶
Parameter	Type	Description
volumeType	String	Disk type. The options are as follows: SSD: ultra-high I/O disk GPSSD: general-purpose SSD SAS: high I/O disk
size	String	Disk size, in GiB.

**Table 31** DataVolumeItem¶
Parameter	Type	Description
volumeType	String	Disk type. The options are as follows: SSD: ultra-high I/O disk GPSSD: general-purpose SSD SAS: high I/O disk
size	String	Disk size, in GiB.
count	Integer	Number of disks.
extendParams	VolumeExtendParams object	Custom disk configuration.

**Table 32** VolumeExtendParams¶
Parameter	Type	Description
volumeGroup	String	Name of a disk group, which is used to divide storage space. The options are as follows: 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 33** VolumeGroupConfig¶
Parameter	Type	Description
volumeGroup	String	Disk group name. Index of the volume group in the dataVolumes.
dockerThinPool	Integer	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.
types	Array of strings	Storage type. The options are as follows: volume: cloud hard disk. When dataVolumes is specified, the default value is used. local: local disk. This parameter must be specified when a local disk is used.

**Table 34** LvmConfig¶
Parameter	Type	Description
lvType	String	LVM write mode. The options are as follows: linear: linear mode. striped: striped mode in which multiple disks are used to form a strip to improve disk performance.
path	String	Disk mount path. This parameter takes effect only in user configuration. The value is an absolute path. Digits, letters, periods (.), hyphens (-), and underscores (_) are allowed.

**Table 35** PoolNetwork¶
Parameter	Type	Description
name	String	Network name. The value is obtained from the metadata.name field in the network resource details.

**Table 36** PoolClusterContainerNetwork¶
Parameter	Type	Description
mode	String	Container network model. The options are as follows: 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.
cidr	String	Container network segment. This parameter is valid only when the container network model is overlay_l2 or vpc-router.

**Table 37** PoolClusterMaster¶
Parameter	Type	Description
az	String	AZ where the master node is located

**Table 38** 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.
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 39** 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	PoolResourceStatus object	The amount of resources in different states in the resource pool.
scope	Array of PoolScopeStatus objects	Service status of a resource pool.
driver	PoolDriverListStatus 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.

**Table 40** PoolResourceStatus¶
Parameter	Type	Description
creating	Array of PoolResourceFlavorCount objects	Data model for the number of resources of the specified specifications
available	Array of PoolResourceFlavorCount objects	Data model for the number of resources of the specified specifications
abnormal	Array of PoolResourceFlavorCount objects	Data model for the number of resources of the specified specifications
deleting	Array of PoolResourceFlavorCount objects	Data model for the number of resources of the specified specifications

**Table 41** PoolResourceFlavorCount¶
Parameter	Type	Description
flavor	String	Resource flavor name, for example, modelarts.vm.gpu.tnt004.
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.
azs	Array of PoolNodeAz objects	AZ where resource pool nodes are deployed.
creatingStep	CreatingStep object	Batch creation information.

**Table 42** PoolNodeAz¶
Parameter	Type	Description
az	String	AZ name.
count	Integer	Number of nodes for expanding the capacity of a specified AZ.

**Table 43** CreatingStep¶
Parameter	Type	Description
step	Integer	Creation step.
type	String	Batch creation type. rack: entire rack hyperinstance: supernodes

**Table 44** PoolScopeStatus¶
Parameter	Type	Description
scopeType	String	Enabled job types. The options are as follows: Train: training jobs Infer: inference jobs Notebook: notebook jobs
state	String	Service status. The options are as follows: Enabling: The service is being enabled. Enabled: The service has been enabled. EnableFailed: The service fails to be enabled. Disabling: The service is being disabled. Disabled: The service has been disabled.
plugins	Array of PoolScopePluginPhase objects	Plug-in status.
message	String	Cause of the failure to enable or disable the environment.

**Table 45** PoolScopePluginPhase¶
Parameter	Type	Description
name	String	Plug-in type.
phase	String	Plug-in status. The options are as follows: Pending: The plug-in is pending. Running: The plug-in is running. Updating: The plug-in is being updated. Abnormal: The plug-in is abnormal. Deleting: The plug-in is being deleted.

**Table 46** PoolDriverListStatus¶
Parameter	Type	Description
gpu	PoolDriverStatus object	GPU driver information.
npu	PoolDriverStatus object	NPU driver information.

**Table 47** 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.

Status code: 400

**Table 48** Response body parameters¶
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 409

**Table 49** 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": "v2",
    "metadata": {
        "annotations": {
            "os.modelarts/description": ""
        },
        "labels": {
            "os.modelarts/name": "pool-ae01",
            "os.modelarts/workspace.id": "0"
        }
    },
    "spec": {
        "type": "Dedicate",
        "scope": [
            "Train"
        ],
        "network": {
            "name": "network-21e1-6f5da086876d4cd084d36f8bd3346036"
        },
        "resources": [
            {
                "count": 1,
                "flavor": "modelarts.vm.cpu.8ud",
            }
        ]
    }
}

Example Responses¶

Status code: 200

{
  "kind" : "Pool",
  "apiVersion" : "v2",
  "metadata" : {
    "name" : "pool-ae01-6f5da086876d4cd084d36f8bd3346036",
    "creationTimestamp" : "2024-10-24T12:42:43Z",
    "labels" : {
      "os.modelarts/name" : "pool-ae01",
      "os.modelarts/workspace.id" : "0",
      "os.modelarts/node.prefix" : "",
      "os.modelarts/resource.id" : "maos-pool-ae01-d7mjs",
      "os.modelarts/tenant.domain.id" : "75fef1f8a9d64d0cb8de795599185b48",
      "os.modelarts/tenant.project.id" : "6f5da086876d4cd084d36f8bd3346036",
      "os.modelarts.pool/biz" : "private",
      "os.modelarts/create-from" : "console"
    },
    "annotations" : {
      "os.modelarts/billing.mode" : "0",
      "os.modelarts.pool/subpools.count" : "0",
      "os.modelarts/flavor.resource.ids" : "{\"modelarts.vm.cpu.8ud\":\"maos.vm.cpu.8ud.1976103046\"}",
      "os.modelarts/tenant.domain.name" : "ei_batch_t00420620_01"
    }
  },
  "spec" : {
    "type" : "Dedicate",
    "scope" : [ "Train" ],
    "resources" : [ {
      "flavor" : "modelarts.vm.cpu.8ud",
      "count" : 1,
      "maxCount" : 1
    } ],
    "network" : {
      "name" : "network-21e1-6f5da086876d4cd084d36f8bd3346036"
    }
  },
  "status" : {
    "resources" : { }
  }
}

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: 2025-08-26 08:17 UTC - commit: 1ba1873d960563c60759f67898a855d9ba3c3502