Creating a Notebook Instance

Updated on 2025-03-14 GMT+08:00

View PDF

Function

You can create a notebook instance based on the specified instance specifications, AI engine images, and storage parameters. You can access the notebook instance through the web page or SSH client.

Calling this API is an asynchronous operation. You can obtain the status of a notebook instance by calling the API for querying notebook instance details.

Constraints

None

Debugging

You can debug this API through automatic authentication in API Explorer 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 contains a maximum of 512 characters and cannot contain the following characters: &<>"'/.
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	This section describes how to configure the local IDE (such as PyCharm and VS Code) or SSH client to remotely access 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
image_id	Yes	String	Specifies the image ID of the notebook instance to be created. The image ID is in the Universally Unique Identifier (UUID) format. You can obtain the image ID by calling the ListImage.xml interface.
name	Yes	String	Instance name, which contains a maximum of 128 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.
service	No	String	Supported service. Possible values are as follows: NOTEBOOK: You can access notebook instances using HTTPS. SSH: You can remotely access notebook instances through SSH.
key_pair_names	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. 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 DevEnvironSelecting Storage in DevEnviron](https://support.huaweicloud.com/en-us/usermanual-standard-modelarts/devtool-modelarts_0004.html#section4)Selecting Storage in DevEnviron](https://support.huaweicloud.com/intl/en-us/devtool-modelarts/devtool-modelarts_0185.html). Enums: SFS EVS
ownership	Yes	String	Owner to which the resource belongs. Enums: MANAGED: Resources are managed by the service. DEDICATED: Resources are managed by the user account. This mode is supported only when the instance category is EFS.
uri	No	String	Disk URI of the EFS. This parameter is mandatory only when the instance category is EFS and the ownership is DEDICATED. Log in to the SFS console. In the file system list, click the file system name to go to the file system details page. The shared path is the value of this parameter.
id	No	String	Disk ID of the EFS. This parameter is mandatory only when the instance category is EFS and the ownership is DEDICATED. This parameter is mandatory. To obtain the parameter value, log in to the SFS console. In the file system list, click the file system name to go to the file system details page. ID is the value of this parameter.

**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. COMMAND: The script content (Base64-encoded) must be specified. SCRIPT (default): The script path must be specified.

**Table 8** LeaseReq
Parameter	Mandatory	Type	Description
duration	No	Long	Indicates the running duration starting from the current time. After the running duration expires, the system automatically stops. 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	This section describes how to configure the local IDE (such as PyCharm and VS Code) or SSH client to remotely access 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 being stopped. DELETING: The instance is being deleted. RUNNING: The instance is running. STOPPED: The instance has been 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 information 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.
billing_items	Array of strings	Type of a charging resource. Options: STORAGE: Storage resources are charged. COMPUTE: Computing resources are charged. ALL: all charging types
user	user object	Account information.

**Table 10** JobProgress
Parameter	Type	Description
notebook_id	String	Instance ID.
status	String	Job status in a specified step. Enums: 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	Path for accessing the notebook instance. The enumerated values are as follows: 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.
service	String	Path for accessing the notebook instance. The enumerated values are as follows: NOTEBOOK: You can access notebook instances using HTTPS. SSH: You can remotely access the notebook instance through SSH.
uri	String	Private IP address of the instance

**Table 12** Image
Parameter	Type	Description
arch	String	Processor architecture supported by the image. Enums: 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. Enums: NOTEBOOK: You can access a notebook instance using HTTPS. SSH: You can remotely access a notebook instance from a local IDE through SSH.
id	String	Specifies the image ID of the notebook instance to be created. The image ID is in the Universally Unique Identifier (UUID) format. For details about how to obtain the ID of a preset image, see ListImage.xml.
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. This parameter is optional. Enums: CUSTOMIZE: custom image IMAGE_SAVE: image saved by a notebook instance
resource_categories	Array of strings	Flavors supported by the image. Enums: CPU GPU ASCEND
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	Specifies the image size, in 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. Enums: CPU GPU ASCEND
swr_path	String	SWR image address
tag	String	Image tag
type	String	Image type. Enums: BUILD_IN: built-in system image DEDICATED: image you have saved
update_at	Long	Specifies the time (UTC ms) when the image was last updated.
visibility	String	Image visibility. Enums: 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.
flavor_type	String	Image resource type. The value can be: ASCEND_SNT9 ASCEND_SNT9B ASCEND_SNT3

**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. timing: The task is automatically stopped. idle: The task is stopped when it is idle.
update_at	Long	Time when the instance is last updated (excluding the heartbeat detection time), in UTC milliseconds.

**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. Enums: SFS 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. Enums: MANAGED: Resources are managed by the service. 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.

**Table 16** user
Parameter	Type	Description
domain	domain object	Account domain information.
id	String	IAM user ID.
name	String	IAM username.

**Table 17** domain
Parameter	Type	Description
id	String	Account ID.
name	String	Account name.

Example Requests

The following is an example of how to create a notebook instance whose flavor is modelarts.vm.cpu.2u, storage type is evs, ownership is MANAGED, and storage capacity is 50 GB.

{
  "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" : "evs",
    "ownership" : "managed",
    "capacity" : 50
  }
}

Example Responses

Status code: 200

{
  "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"
}