Help Center> ModelArts> API Reference> Historical APIs> DevEnviron (Old Version)> Creating a Development Environment Instance
Updated on 2023-12-14 GMT+08:00

Creating a Development Environment Instance

Function

This API is used to create a development environment instance for code development.

Calling this API is an asynchronous operation. The job status can be obtained by calling the API described in Obtaining Details About a Development Environment Instance.

URI

POST /v1/{project_id}/demanager/instances

Table 1 describes the required parameters.
Table 1 Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain a project ID, see Obtaining a Project ID and Name.

Request Body

Table 2 describes the request parameters.
Table 2 Parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Instance name, which contains a maximum of 64 characters.

The value can contain letters, digits, hyphens (-), and underscores (_).

profile_id

Yes

String

Configuration ID. Options:

  • Ascend-Power-Engine 1.0(python3)
  • Multi-Engine 1.0 (python2)-cpu
  • Multi-Engine 1.0 (python2)-gpu
  • Multi-Engine 1.0 (python3)-cpu
  • Multi-Engine 1.0 (python3)-gpu
  • Multi-Engine 2.0 (python3)

description

No

String

Instance description. The value contains a maximum of 512 characters and cannot contain the following special characters: &<>"'/. By default, this parameter is left blank.

flavor

Yes

String

Instance flavor. Options:

  • modelarts.vm.cpu.2u
  • modelarts.vm.cpu.8u
  • modelarts.vm.gpu.p100

The preceding flavors are for reference only. The actual flavors depend on the region. To use other flavors, submit a service ticket to change the flavors.

spec

Yes

Object

Instance definition. Only Notebook is supported. For example, see Table 3.

workspace

No

Object

Workspace. The default workspace ID is 0. For details, see Table 7.

pool

No

Object

Resource pool. For details, see Table 8.

ai_project

No

Object

AI project. For details, see Table 10.

Table 3 notebook parameters

Parameter

Mandatory

Type

Description

storage

Yes

Object

Storage path. For details, see Table 4.

extend_storage

No

Array<Storage>

Extended storage list. For details, see Table 4. Extended storage supports only obsfs and is available only for certain dedicated resource pools.

auto_stop

No

Object

Auto stop parameter. For details, see Table 6.

annotations

No

Map<String,String>

Label information, which can be extended. By default, this parameter is left blank.

Table 4 storage parameters

Parameter

Mandatory

Type

Description

type

Yes

String

Storage type.

Only obs, obsfs, and evs are supported. Additionally, obsfs can only be used in certain dedicated resource pools. To mount an OBS parallel file system, submit a service ticket.

location

No

Object

Storage location. If type is set to obs, this parameter is mandatory. See Table 5. By default, this parameter is left blank.

Table 5 location parameters

Parameter

Mandatory

Type

Description

path

No

String

Storage path

  • If type is set to obs, this parameter is mandatory. The value must be a valid OBS bucket path and end with a slash (/). The value must be a specific directory in an OBS bucket rather than the root directory of an OBS bucket.
  • If type is set to obsfs, the parameter value must be a valid bucket name of the OBS parallel file system. (CCE does not support subdirectory mounting.)
  • If type is set to evs, this parameter does not need to be set.

volume_size

No

Integer

EVS disk size. The minimum size is 5 GB and the maximum size is 4,096 GB. The default value is 5 GB. If type is set to obs, this parameter does not need to be set.

mount_path

No

String

Mount path in a notebook instance. This parameter is valid only when type is set to obsfs.

The default value is /home/ma-user/work.

If you want to mount the file system to a specified path, set the value to the subdirectory of /home/ma-user/work. Otherwise, the mounting may fail or read/write exceptions may occur due to permission issues.

access_modes

No

String

Access permission for the mounted file or folder. The permission can be read/write or read-only. This parameter is valid only when type is set to obsfs. Options:

  • ReadOnlyMany: read-only mode
  • ReadWriteMany: read/write mode (default value)
Table 6 auto_stop parameters

Parameter

Mandatory

Type

Description

enable

No

Boolean

Whether to enable the auto stop function. The value true indicates that the function is enabled and the instance will automatically stop when the running duration is reached. The value false indicates that the function is disabled. The default value is false.

duration

No

Integer

Running duration, in seconds. The value ranges from 3,600 to 86,400. After this parameter is set, it is valid for each startup. This parameter is mandatory when enable is set to true.

prompt

No

Boolean

Whether to display a prompt again. This parameter is provided for the console to determine whether to display a prompt again. The default value is true.

Table 7 workspace parameters

Parameter

Mandatory

Type

Description

id

No

String

Workspace ID. If no workspace is created, the default value is 0. If a workspace is created and used, use the actual value.

Table 8 poolSpec parameters

Parameter

Mandatory

Type

Description

id

Yes

String

Resource pool ID.

type

No

String

Resource pool type.

name

No

String

Resource pool name.

owner

No

Object

Owner of the resource pool. For details, see Table 9.

Table 9 userSpec parameters

Parameter

Mandatory

Type

Description

project_id

No

String

ID of the project to which the resource belongs.

Table 10 AIProject parameters

Parameter

Mandatory

Type

Description

id

No

String

AI project ID. This parameter is reserved.

Response Body

Table 11 describes the response parameters.
Table 11 Parameters

Parameter

Type

Description

id

String

Instance ID

name

String

Instance name

description

String

Instance description

status

String

Instance status

creation_timestamp

String

Time when an instance is created

latest_update_timestamp

String

Time when an instance is modified

profile

Object

Configuration information. For details, see Table 12.

flavor

String

Instance flavor

flavor_details

Object

For details about the flavor, see Table 16.

pool

Object

For details about the dedicated resource pool, see Table 17.

spec

Object

Instance definition For details about parameters of a notebook instance, see Table 19.

workspace

Object

Workspace. For details, see Table 24.

ai_project

Object

AI project. For details, see Table 25.

error_code

String

Error code. For details, see Error Codes.

queuing_info

Object

Queuing information. For details, see Table 26.

user

Object

User information. For details, see Table 27.

repository

Object

Git repository information. For details, see Table 28. This parameter cannot be used. It is automatically returned when the API is called.

Table 12 profile parameters

Parameter

Type

Description

id

String

Configuration ID

name

String

Configuration name

description

String

Configuration description

de_type

String

Development environment type. Only Notebook is supported.

flavor_type

String

Hardware, which can be CPU, GPU, or Ascend.

provision

Object

Deployment information. For details, see Table 13.

labels

Map<String,String>

Label

Table 13 provision parameters

Parameter

Type

Description

type

String

Deployment type. Only Docker is supported.

spec

Object

Deployment details. For details, see Table 14.

Table 14 spec parameters

Parameter

Type

Description

engine

String

Deployment engine. Only CCE is supported.

params

Object

Deployment parameters. Only Docker is supported. For details, see Table 15.

Table 15 Docker deployment parameters

Parameter

Type

Description

namespace

String

SWR organization name, which is globally unique

image_name

String

Image name

image_tag

String

Image tag

annotations

Map<String,String>

Label information, which can be extended. By default, this parameter is left blank.

Table 16 flavor_details parameters

Parameter

Type

Description

name

String

Flavor name

status

String

Flavor sales status. Options:

  • onSale
  • soldOut

queuing_num

Integer

This parameter is mandatory when promo_type is set to Free and status is set to soldOut.

queue_left_time

Integer

Left queuing time, in seconds

This parameter is mandatory when promo_type is set to Free and status is set to soldOut.

storage_list

Array<Storage type>

Supported storage type. Options:

  • obs
  • evs
  • efs

is_permitted

Boolean

Whether the current user has the permission to use this flavor

type

String

Flavor type. Options:

  • GPU
  • CPU
  • ASCEND

params

Dict

Parameters that describing flavor

promo_type

String

Promotion type. Options:

  • Free
  • NoDiscount

instance_num

Integer

Number of instances of this flavor the current created

duration

Integer

Auto stop time after startup, in seconds

store_time

Integer

Maximum retention period of an inactive instance of this flavor in the database, in hours

The default value is -1, indicating that the instance can be permanently saved.

billing_flavor

String

Billing specifications. If this field is left blank, the specifications name is used for billing.

billing_params

Integer

Billing ratio This parameter is mandatory when billing_flavor is specified.

Table 17 pool parameters

Parameter

Type

Description

id

String

ID of a resource pool

name

String

Name of a resource pool

type

String

Type of a resource pool. USER_DEFINED indicates a dedicated resource pool.

owner

Object

This parameter is mandatory when type is set to USER_DEFINED. For details, see Table 18.

Table 18 owner parameters

Parameter

Type

Description

project_id

String

Project ID

Table 19 notebook parameters

Parameter

Type

Description

log_path

String

Path for storing custom image logs

custom_script_path

String

Path for storing custom initialization scripts used when a notebook instance is started

extend_storage

Array<Storage>

Extended storage list. For details, see Table 20. Extended storage supports only obsfs and is available only for certain dedicated resource pools.

storage

Object

Storage path. For details, see Table 20.

credential

Object

AK and SK for accessing OBS. For details, see Table 30.

repository

Object

Git repository information. For details, see Table 28. This parameter cannot be used. It is automatically returned when the API is called.

resource_reserved_timestamp

Integer

Time when the resource is reserved

auto_stop

Object

Auto stop parameter. For details, see Table 23.

failed_reasons

Object

Cause for a creation or startup failure. For details, see Table 22.

annotations

Map<String,String>

Annotations

The generated URL cannot be directly accessed.

extend_params

Map<String,String>

Extended parameter

Table 20 storage parameters

Parameter

Type

Description

type

String

Storage type.

Only obs, obsfs, and evs are supported. Additionally, obsfs can only be used in certain dedicated resource pools. To mount an OBS parallel file system, submit a service ticket.

location

Object

Storage location. If type is set to obs, this parameter is mandatory. See Table 21. By default, this parameter is left blank.

Table 21 location parameters

Parameter

Type

Description

path

String

Storage path

  • If type is set to obs, this parameter is mandatory. The value must be a valid OBS bucket path and end with a slash (/). The value must be a specific directory in an OBS bucket rather than the root directory of an OBS bucket.
  • If type is set to obsfs, the parameter value must be a valid bucket name of the OBS parallel file system. (CCE does not support subdirectory mounting.)
  • If type is set to evs, this parameter does not need to be set.

volume_size

Integer

EVS disk size. The minimum size is 5 GB and the maximum size is 4,096 GB. The default value is 5 GB. If type is set to obs, this parameter does not need to be set.

mount_path

String

Mount path in a notebook instance. This parameter is valid only when type is set to obsfs.

The default value is /home/ma-user/work.

If you want to mount the file system to a specified path, set the value to the subdirectory of /home/ma-user/work. Otherwise, the mounting may fail or read/write exceptions may occur due to permission issues.

access_modes

String

Access permission for the mounted file or folder. The permission can be read/write or read-only. This parameter is valid only when type is set to obsfs. Options:

  • ReadOnlyMany: read-only mode
  • ReadWriteMany: read/write mode (default value)
Table 22 failed_reasons parameters

Parameter

Type

Description

code

String

Error code.

message

String

Error message

detail

Map<String,String>

Error details

Table 23 auto_stop parameters

Parameter

Type

Description

enable

Boolean

Whether to enable the auto stop function

duration

Integer

Running duration, in seconds

prompt

Boolean

Whether to display a prompt again. This parameter is provided for the console to use.

stop_timestamp

Integer

Time when the instance stops. The value is a 13-digit timestamp.

remain_time

Integer

Remaining time before actual stop, in seconds

Table 24 workspace parameters

Parameter

Type

Description

id

String

Workspace ID

Table 25 AIProject parameters

Parameter

Type

Description

id

String

AI project ID

Table 26 queuing_info parameters

Parameter

Type

Description

id

String

Instance ID

name

String

Instance name

de_type

String

Development environment type. By default, all types are returned.

Only Notebook is supported.

flavor

String

Instance flavor. By default, all types are returned. Options:

  • modelarts.vm.cpu.free
  • modelarts.vm.gpu.free

flavor_details

Object

Flavor details, which display the flavor information and whether the flavor is sold out For details, see Table 16.

status

String

Instance status. By default, all statuses are returned, including:

  • CREATE_QUEUING
  • START_QUEUING

begin_timestamp

Integer

Time when an instance starts queuing. The value is a 13-digit timestamp.

remain_time

Integer

Left queuing time, in seconds

end_timestamp

Integer

Time when an instance completes queuing. The value is a 13-digit timestamp.

rank

Integer

Ranking of an instance in a queue

Table 27 user parameters

Parameter

Type

Description

id

String

User ID

name

String

Username

Table 28 repository parameters

Parameter

Type

Description

id

String

Repository ID

branch

String

Repository branch

user_name

String

Repository username

user_email

String

Repository user mailbox

type

String

Repository type. The options are CodeClub and GitHub.

connection_info

Object

Repository link information. For details, see Table 29.

Table 29 connection_info parameters

Parameter

Type

Description

protocol

String

Repository link protocol. The options are ssh and https.

url

String

Repository link address

credential

Object

Certificate information. For details, see Table 30.

Table 30 credential parameters

Parameter

Type

Description

ssh_private_key

String

SSH private certificate

access_token

String

OAuth token of GitHub

Sample Request

The following shows how to create the notebook-instance instance with ID Python3-gpu.

  • Sample request
    {
        "name": "notebook-instance",
        "description": "",
        "profile_id": "Multi-Engine 1.0 (python3)-gpu",
        "flavor": "modelarts.bm.gpu.v100NV32",
        "spec": {
            "storage": {
                "location": {
                    "volume_size": 5
                },
                "type": "evs"
            },
            "auto_stop": {
                "enable": true,
                "duration": 3600
            }
        },
        "workspace": {
            "id": "0"
        }
    }

Sample Response

  • Successful response
    {
        "ai_project": {
            "id": "default-ai-project"
        },
        "creation_timestamp": "1594887749962",
        "description": "",
        "flavor": "modelarts.bm.gpu.v100NV32",
        "flavor_details": {
            "name": "modelarts.bm.gpu.v100NV32",
            "params": {
                "CPU": 8,
                "GPU": 1,
                "gpu_type": "v100NV32",
                "memory": "64GiB"
            },
            "status": "onSale",
            "type": "GPU"
        },
        "id": "DE-7d558ef8-c73d-11ea-964c-0255ac100033",
        "latest_update_timestamp": "1594887749962",
        "name": "notebook-c6fd",
        "profile": {
            "de_type": "Notebook",
            "description": "multi engine, gpu, python 3.6 for notebook",
            "flavor_type": "GPU",
            "id": "Multi-Engine 1.0 (python3)-gpu",
            "name": "Multi-Engine 1.0 (python3)-gpu",
            "provision": {
                "spec": {
                    "engine": "CCE",
                    "params": {
                        "image_name": "mul-kernel-gpu-cuda-cp36",
                        "image_tag": "2.0.5-B003",
                        "namespace": "atelier"
                    }
                },
                "type": "Docker"
            }
        },
        "spec": {
            "annotations": {
                "target_domain": "https://modelarts-notebook-2.xxxx.com",
                "url": ""
            },
            "auto_stop": {
                "duration": 3600,
                "enable": true,
                "prompt": true
            },
            "storage": {
                "location": {
                    "path": "/home/ma-user/work",
                    "volume_size": 5
                },
                "type": "evs"
            }
        },
        "status": "CREATING",
        "user": {
            "id": "15dda26361214ca2a5953917d2f48ffb",
            "name": "ops_dev_env"
        },
        "workspace": {
            "id": "0"
        }
    }
  • Failed response
    {
        "error_message": "The param path needs to end with /.",
        "error_code": "ModelArts.6318"
    }

Status Code

For details about the status code, see Status Code.