Creating a Notebook Instance

Function

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

Constraints

None

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.

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 calculated from the current time, in milliseconds. The instance automatically stops when the duration expires.
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. Currently, the following flavors are supported: modelarts.vm.cpu.2u: General-purpose Intel CPU flavors, ideal for rapid data exploration and tests. 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. The preceding flavors are for reference only. The actual flavors depend on the region.
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 that can be duplicate. The name can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_).
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 workspace is created, the default value is 0. If a workspace is created and used, use the actual value.

**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 services. Options: NOTEBOOK: You can access the notebook instance 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 4,096 GB.
category	Yes	String	Storage category. Options: EFS: Scalable File Service (SFS), which is the default storage. EVS: Elastic Volume Service (EVS).
ownership	Yes	String	Owner to which the resource belongs. Options: MANAGED: Resources are managed by services. DEDICATED: Resources are managed by the 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/.

Response Parameters

Status code: 200

**Table 5** 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
feature	String	Instance type. Options: DEFAULT: free CodeLab instance. You can create only one. NOTEBOOK: billed instance.
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: A snapshot is being taken for the instance (status when the image is being saved). CREATE_FAILED: The instance fails to be created. START_FAILED: The instance fails to be started. DELETE_FAILED: The instance fails to be deleted. ERROR: An error occurs. DELETED: The instance is 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 workspace is created, the default value is 0. If a workspace is created and used, use the actual value.

**Table 6** JobProgress
Parameter	Type	Description
notebook_id	String	Instance ID.
status	String	Job status in a specified step. Options: WAITING: The job is waiting to begin. PROCESSING: The job is being processed. FAILED: The job failed. COMPLETED: The task is complete.
step	Integer	Job step. Options: 1: Storage preparation. 2: Computing resource preparation. 3: Network configurations. 4: Instance initialization.
step_description	String	Description of a step in a job.

**Table 7** 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 services. Options: NOTEBOOK: You can access the notebook instance 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 8** Image
Parameter	Type	Description
id	String	Image ID
name	String	Image name.
swr_path	String	SWR image address
type	String	Image type. Options: BUILD_IN: built-in system image DEDICATED: image saved by the user

**Table 9** Lease
Parameter	Type	Description
create_time	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.
update_time	Long	Time (UTC) when the instance is last updated (excluding the keepalive heartbeat time), accurate to millisecond.

**Table 10** Pool
Parameter	Type	Description
id	String	ID of a dedicated resource pool
name	String	Name of a dedicated resource pool

**Table 11** 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 4,096 GB.
category	String	Storage category. Options: EFS: Scalable File Service (SFS), which is the default storage. EVS: Elastic Volume Service (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 services. DEDICATED: Resources are managed by the 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

{
  "action_progress" : [ {
    "step" : 1,
    "status" : "WAITING",
    "description" : "Prepare the storage."
  }, {
    "step" : 2,
    "status" : "WAITING",
    "description" : "Prepare the compute resource."
  }, {
    "step" : 3,
    "status" : "WAITING",
    "description" : "Configuring the network."
  }, {
    "step" : 4,
    "status" : "WAITING",
    "description" : "Initialize the notebook instance."
  } ],
  "create_at" : 1638841744521,
  "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.xxx.xxxx.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,
    "update_at" : 1638841744515
  },
  "name" : "notebooks_test",
  "status" : "CREATING",
  "token" : "3eff13f2-3d70-5456-6dc7-e3f99f562022",
  "update_at" : 1638841744522,
  "workspace_id" : "0"
}