Creating a Notebook Instance

Function

This API is used to create a notebook instance based on the specified flavor, AI engine image, and storage. You can access the instance through a web page or SSH client. Calling this API is an asynchronous operation. The job status can be obtained by calling the API for obtaining details about a development environment instance.

Constraints

None

Debugging

You can debug this API through automatic authentication in or use the SDK sample code generated by API Explorer.

URI

POST /v1/{project_id}/notebooks

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 body parameters

Parameter

Mandatory

Type

Description

description

No

String

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

duration

No

Long

Running duration starting from the current time. It is recommended that this attribute be configured in leaseReq. If this attribute has a value, the value of leaseReq is ignored and the automatic instance stop type is scheduled stop. Unit: ms.

endpoints

No

Array of EndpointsReq objects

Local IDE (such as PyCharm and vsCode) or SSH client for remotely accessing a notebook instance through SSH.

feature

No

String

Instance type. The default value is NOTEBOOK. Options:

  • DEFAULT: free CodeLab instance. You can create only one.

  • NOTEBOOK: billed instance.

flavor

Yes

String

Instance flavor. The following flavors are for reference only. Obtain the flavors displayed on the console in the target region.

  • modelarts.vm.cpu.2u: General-purpose Intel CPU flavor, ideal for rapid data exploration and experiments

  • modelarts.vm.cpu.8u: General computing-plus Intel CPU flavors, ideal for compute-intensive applications

  • modelarts.bm.gpu.v100NV32: One NVIDIA V100 GPU with 32 GB of memory, ideal for training and debugging deep learning algorithms

  • modelarts.bm.d910.xlarge.1: One Arm-powered Ascend 910 processor with 32 GB of GPU memory, ideal for training and debugging deep learning models

  • modelarts.bm.d910.xlarge.2: Two Arm-powered Ascend 910 processors with 32 GB of GPU memory, ideal for training and debugging deep learning models

  • modelarts.bm.d910.xlarge.8: Eight Arm-powered Ascend 910 processors with 32 GB of GPU memory, ideal for training and debugging deep learning models

image_id

Yes

String

ID of the image used for creating notebook instances. The ID is in Universally Unique Identifier (UUID) format. For details, see Querying Supported Images.

name

Yes

String

Instance name, which contains a maximum of 64 characters, including letters, digits, hyphens (-), and underscores (_). Instance names can be duplicate.

pool_id

No

String

ID of a dedicated resource pool, for example, pool41664192. This parameter is mandatory if a dedicated resource pool needs to be specified for creating an instance.

volume

Yes

VolumeReq object

Storage volume.

workspace_id

No

String

Workspace ID. If no workspaces are available, the default value is 0.

hooks

No

CustomHooks object

Customized startup script hook configuration.

lease

No

LeaseReq object

Instance lease configuration.

Table 3 EndpointsReq

Parameter

Mandatory

Type

Description

allowed_access_ips

No

Array of strings

Public IP addresses that can remotely access the notebook instance. A maximum of five public IP addresses are supported.

dev_service

No

String

Supported service. Options:

  • NOTEBOOK: You can access notebook instances using HTTPS.

  • SSH: You can remotely access the notebook instance through SSH.

ssh_keys

No

Array of strings

Name of the SSH key pair, which can be created and viewed on the Key Pair page of the Elastic Cloud Server (ECS) console.

Table 4 VolumeReq

Parameter

Mandatory

Type

Description

capacity

No

Integer

Storage capacity. The default value is 5 GB for EVS and 50 GB for EFS. The maximum value is 4096 GB.

category

Yes

String

Supported storage types. For details about the differences between the storage types, see "Selecting Storage in DevEnviron" in User Guide. Options:

  • EFS: Scalable File Service, which is the default storage

  • EVS

ownership

Yes

String

Owner to which the resource belongs. Options:

  • MANAGED: Resources are managed by service.

  • DEDICATED: Resources are managed by user account. This mode is supported only when the instance category is EFS.

uri

No

String

URI of the EFS. This parameter is mandatory only when the instance category is EFS and ownership is DEDICATED. An example URI is 192.168.0.1:/user-9sfdsdgdfgh5ea4d56871e75d6966aa274/mount/.

Table 5 CustomHooks

Parameter

Mandatory

Type

Description

container_hooks

No

ContainerHooks object

Container-related hook configuration.

Table 6 ContainerHooks

Parameter

Mandatory

Type

Description

post_start

No

Config object

Configure the script after the service is started.

pre_start

No

Config object

Configure the script before starting the service.

Table 7 Config

Parameter

Mandatory

Type

Description

script

No

String

User-defined script content (Base64 encoding) or absolute script path.

type

No

String

Script type. The options are as follows:

  • The script content (Base64 encoding) must be specified in COMMAND script.

  • Default value of SCRIPT. The script path must be specified in the script.

Table 8 LeaseReq

Parameter

Mandatory

Type

Description

duration

No

Long

Scheduled stop: The running duration starts from the current time and automatically stops when the running duration expires. Idle stop: indicates the idle duration starting from the current time. When the idle duration exceeds the idle duration, the system automatically stops. The minimum idle stop value is 900000. Unit: ms.

type

No

String

Automatic stop type. The default value is timing.

Response Parameters

Status code: 200

Table 9 Response body parameters

Parameter

Type

Description

action_progress

Array of JobProgress objects

Instance initialization progress.

description

String

Instance description

endpoints

Array of EndpointsRes objects

Local IDE (such as PyCharm and vsCode) or SSH client for remotely accessing a notebook instance through SSH.

fail_reason

String

Instance failure cause

flavor

String

Instance flavor

id

String

Instance ID.

image

Image object

Instance image

lease

Lease object

Countdown to automatic instance stop.

name

String

Instance name

pool

Pool object

Basic information about the dedicated pool, which is returned by the instance created in the dedicated pool.

status

String

Instance status. Options:

  • INIT: The instance is being initialized.

  • CREATING: The instance is being created.

  • STARTING: The instance is starting.

  • STOPPING: The instance is stopping.

  • DELETING: The instance is being deleted.

  • RUNNING: The instance is running.

  • STOPPED: The instance is stopped.

  • SNAPSHOTTING: The image of the instance is being saved.

  • CREATE_FAILED: Creating the instance failed.

  • START_FAILED: Starting the instance failed.

  • DELETE_FAILED: Deleting the instance failed.

  • ERROR: An error occurred.

  • DELETED: The instance has been deleted.

  • FROZEN: The instance is frozen.

token

String

Token used for notebook authentication

url

String

URL for accessing the notebook instance

volume

VolumeRes object

Storage volume

workspace_id

String

Workspace ID. If no workspaces are available, the default value is 0.

feature

String

Instance type. Options:

  • DEFAULT: free CodeLab instance. You can create only one.

  • NOTEBOOK: billed instance.

Table 10 JobProgress

Parameter

Type

Description

notebook_id

String

Instance ID.

status

String

Job status in a specified step. Options:

  • WAITING: The job is awaiting.

  • PROCESSING: The job is being processed.

  • FAILED: The job failed.

  • COMPLETED: The job is complete.

step

Integer

Job step. Options:

  • 1: Prepare storage.

  • 2: Prepare compute resources.

  • 3: Configure the network.

  • 4: Initialize the instance.

step_description

String

Description of a step in a job.

Table 11 EndpointsRes

Parameter

Type

Description

allowed_access_ips

Array of strings

Whitelist of public IP addresses that are allowed to access the notebook instance through SSH. By default, all public IP addresses can access the notebook instance. If this parameter is specified, only the clients with the specified IP addresses can access the notebook instance.

dev_service

String

Supported service. Options:

  • NOTEBOOK: You can access notebook instances using HTTPS.

  • SSH: You can remotely access the notebook instance through SSH.

ssh_keys

Array of strings

List of SSH key pairs. You can set multiple key pairs to access an SSH instance at the same time.

Table 12 Image

Parameter

Type

Description

arch

String

Processor architecture supported by the image. Options:

  • X86_64: x86 architecture

  • AARCH64: Arm architecture

create_at

Long

Specifies the time (UTC ms) when the image is created.

description

String

Image description with a maximum of 512 characters

dev_services

Array of strings

Services supported by the image. Options:

  • NOTEBOOK: You can access the notebook instance using HTTPS.

  • SSH: You can remotely access the notebook instance from a local IDE through SSH.

id

String

ID of the image used for creating notebook instances. The ID is in Universally Unique Identifier (UUID) format.For details, see Querying Supported Images.

name

String

Image name, which contains a maximum of 512 characters, including lowercase letters, digits, hyphens (-), underscores (_), and periods (.)

namespace

String

Organization to which the image belongs. You can create and view the organization on the Organization Management page of the SWR console.

origin

String

Image source, which defaults to CUSTOMIZE. Options:

  • CUSTOMIZE: user-defined image

  • IMAGE_SAVE: image saved using a development environment instance

resource_categories

Array of strings

Flavors supported by the image. Options:

  • CPU

  • GPU

service_type

String

Supported image types. Options:

  • COMMON: common image

  • INFERENCE: image used for inference

  • TRAIN: image used for training

  • DEV: image used for development and debugging

  • UNKNOWN: image whose supported services are not specified

size

Long

Image size, in unit of KB

status

String

Image status. Options:

  • INIT: The image is being initialized.

  • CREATING: The image is being saved. In this case, the notebook instance is unavailable.

  • CREATE_FAILED: Saving the image failed.

  • ERROR: An error occurs.

  • DELETED: The image has been deleted.

  • ACTIVE: The image has been saved, which you can view on the SWR console and use to create notebook instances.

status_message

String

Build information during image saving

support_res_categories

Array of strings

Flavors supported by the image. Options:

  • CPU

  • GPU

swr_path

String

SWR image address

tag

String

Image tag

type

String

Image type. Options:

  • BUILD_IN: built-in system image

  • DEDICATED: private image

update_at

Long

Specifies the time (UTC ms) when the image was last updated.

visibility

String

Image visibility. Options:

  • PRIVATE: private image

  • PUBLIC: All users can perform read-only operations based on the image ID.

workspace_id

String

Workspace ID. If no workspaces are available, the default value is 0.

Table 13 Lease

Parameter

Type

Description

create_at

Long

Time (UTC) when the instance is created, accurate to millisecond.

duration

Long

Instance running duration, which is calculated based on the instance creation time. If the instance creation time plus the duration is greater than the current time, the system automatically stops the instance.

enable

Boolean

Whether to enable auto stop of the instance.

type

String

Indicates the automatic stop type.

update_at

Long

Time (UTC) when the instance is last updated (excluding the keepalive heartbeat time), accurate to millisecond.

Table 14 Pool

Parameter

Type

Description

id

String

ID of a dedicated resource pool

name

String

Name of a dedicated resource pool

Table 15 VolumeRes

Parameter

Type

Description

capacity

Integer

Storage capacity. The default value is 5 GB for EVS and 50 GB for EFS. The maximum value is 4096 GB.

category

String

Supported storage types. For details about the differences between the storage types, see "Selecting Storage in DevEnviron" in User Guide. Options:

  • EFS: Scalable File Service, which is the default storage

  • EVS

mount_path

String

Directory of the notebook instance to which OBS storage is mounted. Currently, the directory is /home/ma-user/work/.

ownership

String

Owner to which the resource belongs. Options:

  • MANAGED: Resources are managed by service.

  • DEDICATED: Resources are managed by user account. This mode is supported only when the instance category is EFS.

status

String

EVS disk capacity expansion status, which is RESIZING during capacity expansion and does not affect the instance.

Example Requests

{
  "name" : "notebooks_test",
  "feature" : "NOTEBOOK",
  "workspace_id" : "0",
  "description" : "api-test",
  "flavor" : "modelarts.vm.cpu.2u",
  "image_id" : "e1a07296-22a8-4f05-8bc8-e936c8e54090",
  "volume" : {
    "category" : "efs",
    "ownership" : "managed",
    "capacity" : 50
  }
}

Example Responses

Status code: 200

OK

{
  "description" : "api-test",
  "feature" : "NOTEBOOK",
  "flavor" : "modelarts.vm.cpu.2u",
  "id" : "f9937afa-4451-42db-a76b-72d624749f66",
  "image" : {
    "description" : "description",
    "id" : "e1a07296-22a8-4f05-8bc8-e936c8e54090",
    "name" : "notebook2.0-mul-kernel-cpu-cp36",
    "swr_path" : "swr.xxxxx.com/atelier/notebook2.0-mul-kernel-cpu-cp36:3.3.2-release_v1",
    "tag" : "3.3.2-release_v1",
    "type" : "BUILD_IN"
  },
  "lease" : {
    "create_at" : 1638841744515,
    "duration" : 3600000,
    "enable" : true,
    "type" : "TIMING",
    "update_at" : 1638841744515
  },
  "name" : "notebooks_test",
  "status" : "CREATING",
  "token" : "3eff13f2-3d70-5456-6dc7-e3f99f562022",
  "workspace_id" : "0"
}

Status Codes

Status Code

Description

200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

Error Codes

See Error Codes.

last updated: 2024-11-14 08:44 UTC - commit: 3b80612feba1452e3d3adbec6770d8e1b5070820