Help Center/ ModelArts/ API Reference/ Historical APIs/ DevEnviron (Old Version)/ Creating a Development Environment Instance

Updated on 2024-05-30 GMT+08:00

View PDF

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

Parent topic: DevEnviron (Old Version)

Previous topic: DevEnviron (Old Version)

Next topic: Obtaining Development Environment Instances

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot