matreche/modelarts-umn
1
0
Fork 0
forked from docs/modelarts
Code Issues Pull Requests Packages Projects Releases Wiki Activity
modelarts-umn/api-ref/source/devenviron/creating_a_development_environment_instance.rst

78 KiB
Raw Blame History

original_name

modelarts_03_0110.html

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 Querying Details About a Development Environment Instance <modelarts_03_0112>.

URI

POST /v1/{project_id}/demanager/instances

Table 1 <modelarts_03_0110__en-us_topic_0136223949_table569625523811> describes the required parameters.

Table 1 Parameters
Parameter Mandatory Type Description
project_id Yes String Project ID. For details about how to obtain the project ID, see Obtaining a Project ID <modelarts_03_0147>.

Request Body

Table 2 <modelarts_03_0110__en-us_topic_0136223949_table2542581515> 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. The options are as follows:

  • 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 options are as follows:

  • modelarts.kat1.xlarge
  • modelarts.vm.cpu.2u
  • modelarts.vm.cpu.8u
  • modelarts.vm.gpu.v100

The preceding flavors are for reference only. The actual flavors depend on the region. If you need to use other flavors, contact the system administrator to change the flavors.
spec Yes Object Instance definition. Only Notebook is supported. For example, see Table 3 <modelarts_03_0110__en-us_topic_0136223949_table1661540121718>.
workspace No Object Workspace. The default workspace ID is 0. For details, see Table 7 <modelarts_03_0110__en-us_topic_0136223949_table195831523711>.
pool No Object Resource pool. For details, see Table 8 <modelarts_03_0110__en-us_topic_0136223949_request_poolspec>.
ai_project No Object AI project. For details, see Table 10 <modelarts_03_0110__en-us_topic_0136223949_request_aiproject>.
Table 3 notebook parameters
Parameter Mandatory Type Description
storage Yes Object Storage path. For details, see Table 4 <modelarts_03_0110__en-us_topic_0136223949_table14531721311>.
extend_storage No Array<Storage> Extended storage list. For details, see Table 4 <modelarts_03_0110__en-us_topic_0136223949_table14531721311>. 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 <modelarts_03_0110__en-us_topic_0136223949_table756291982911>.
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 is supported.
location No Object Storage location. If type is set to obs, this parameter is mandatory. See Table 5 <modelarts_03_0110__en-us_topic_0136223949_table10263721145>. 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.
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 <modelarts_03_0110__en-us_topic_0136223949_request_userspec>.
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 <modelarts_03_0110__en-us_topic_0136223949_table1282791914324> 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 <modelarts_03_0110__en-us_topic_0136223949_table14360146192514>.
flavor String Instance flavor
flavor_details Object For details about the flavor, see Table 16 <modelarts_03_0110__en-us_topic_0136223949_table15315195310273>.
pool Object For details about the dedicated resource pool, see Table 17 <modelarts_03_0110__en-us_topic_0136223949_table1757552712913>.
spec Object Instance definition For details about parameters of a notebook instance, see Table 19 <modelarts_03_0110__en-us_topic_0136223949_table8449155512217>.
workspace Object Workspace. For details, see Table 24 <modelarts_03_0110__en-us_topic_0136223949_table11410143081110>.
ai_project Object AI project. For details, see Table 25 <modelarts_03_0110__en-us_topic_0136223949_response_aiproject>.
error_code String Error code. For details, see Error Codes <modelarts_03_0095>.
queuing_info Object Queuing information. For details, see Table 26 <modelarts_03_0110__en-us_topic_0136223949_table1535133818408>.
user Object User information. For details, see Table 27 <modelarts_03_0110__en-us_topic_0136223949_table478950164319>.
repository Object Git repository information. For details, see Table 28 <modelarts_03_0110__en-us_topic_0136223949_table63971252184512>. 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.
provision Object Deployment information. For details, see Table 13 <modelarts_03_0110__en-us_topic_0136223949_table108415111491>.
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 <modelarts_03_0110__en-us_topic_0136223949_table368911231548>.
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 <modelarts_03_0110__en-us_topic_0136223949_table932452015018>.
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 sale status The options are as follows:

  • 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. The options are as follows:

  • obs
is_permitted Boolean Whether the current user has the permission to use this flavor
type String

Flavor status. The options are as follows:

  • GPU
  • CPU
params Dict Parameters that describing flavor
promo_type String

Promotion type. The options are as follows:

  • 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 <modelarts_03_0110__en-us_topic_0136223949_table1532233153818>.
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
storage Object Storage path. For details, see Table 20 <modelarts_03_0110__en-us_topic_0136223949_table9228954163219>.
credential Object AK and SK for accessing OBS. For details, see Table 30 <modelarts_03_0110__en-us_topic_0136223949_table970685216555>.
repository Object Git repository information. For details, see Table 28 <modelarts_03_0110__en-us_topic_0136223949_table63971252184512>. 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 <modelarts_03_0110__en-us_topic_0136223949_table14279174582613>.
failed_reasons Object Cause for a creation or startup failure. For details, see Table 22 <modelarts_03_0110__en-us_topic_0136223949_table72771614152013>.
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 is supported.
location Object Storage location. If type is set to obs, this parameter is mandatory. See Table 21 <modelarts_03_0110__en-us_topic_0136223949_table212131963416>. 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.
volume_size Integer If type is set to obs, this parameter does not need to be set.
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.
flavor_details Object Flavor details, which display the flavor information and whether the flavor is sold out For details, see Table 16 <modelarts_03_0110__en-us_topic_0136223949_table15315195310273>.
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 <modelarts_03_0110__en-us_topic_0136223949_table13487192116490>.
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 <modelarts_03_0110__en-us_topic_0136223949_table970685216555>.
Table 30 credential parameters
Parameter Type Description
ssh_private_key String SSH private certificate
access_token String OAuth token of GitHub

Samples

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

  • Sample request

    {
  "name": "notebook-d115",
  "description": "",
  "profile_id": "Ascend-Power-Engine 1.0(python3)",
  "flavor": "modelarts.kat1.xlarge",
  "spec": {
    "storage": {
      "location": {
        "path": "/aaaaaaaaa/output/"
      },
      "type": "obs"
    },
    "auto_stop": {
      "enable": true,
      "duration": 3600
    }
  },
  "workspace": {
    "id": "0"
  }
}

  • Successful sample response

    {
  "ai_project": {
    "id": "default-ai-project"
  },
  "creation_timestamp": "1614669154682",
  "description": "",
  "flavor": "modelarts.kat1.xlarge",
  "flavor_details": {
    "name": "modelarts.kat1.xlarge",
    "params": {
      "CPU": 24,
      "NPU": 1,
      "graphics_memory": "32GiB",
      "memory": "96GiB",
      "type": "Ascend 910"
    },
    "status": "onSale",
    "storage_list": [
      "obs",
      "efs"
    ],
    "type": "Ascend"
  },
  "id": "DE-a970f5d4-7b26-11eb-91ca-0255ac10003b",
  "latest_update_timestamp": "1614669154682",
  "name": "notebook-d115",
  "profile": {
    "de_type": "Notebook",
    "description": "Ascend 910, python 3.7/3.6 for notebook",
    "flavor_type": "Ascend",
    "id": "efa847c0-7359-11eb-b34f-0255ac100057",
    "name": "Ascend-Powered-Engine 1.0 (python3)",
    "provision": {
      "annotations": {
        "category": "Ascend-Powered-Engine 1.0 (Python3)",
        "type": "system"
      },
      "spec": {
        "engine": "CCE",
        "params": {
          "image_name": "mul-kernel-d910-arm-cp37",
          "image_tag": "3.1.0-c76-2-test",
          "namespace": "atelier"
        }
      },
      "type": "Docker"
    }
  },
  "spec": {
    "annotations": {
      "target_domain": "https://notebook-modelarts.cn-south-222.pcl.ac.cn",
      "url": ""
    },
    "auto_stop": {
      "duration": 3600,
      "enable": true,
      "prompt": true
    },
    "extend_params": null,
    "extend_storage": null,
    "failed_reasons": null,
    "repository": null,
    "storage": {
      "location": {
        "path": "/aaaaaaaaa/output/"
      },
      "type": "obs"
    }
  },
  "status": "CREATING",
  "user": {
    "id": "f3779708b547462dbca12a70555d0690",
    "name": "modelarts_manage_admin"
  },
  "workspace": {
    "id": "0"
  }
}

  • Failed sample 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 <modelarts_03_0094>.

Error Codes

See Error Codes <modelarts_03_0095>.