Dynamic Mounting of Notebook Storage

Function

This API allows you to mount dynamic storage to a specified directory of a running notebook instance. After this API is called, the system mounts the specified storage instance to the notebook instance in asynchronous mode. After the mounting is complete, you can read and write files of the storage instance in the container. If you do not have the permission to access the specified notebook instance or the notebook instance is not running, the API will return an error message.

Supported storage types:

OBS: Select this when OBS buckets are used directly as persistent storage for AI development and exploration. However, frequent read and write performance of small files is poor. Do not use this in model training and large file decompression scenarios. Otherwise, the system may lag when you perform operations on notebook files.
PFS: This high-performance object storage system offers cost-effective storage and fast high throughput. It efficiently handles high-performance computing (HPC) tasks but struggles with frequent small-file reads and writes. The system may lag when you perform operations on notebook files.
SFS Turbo: Only dedicated resource pool instances can be mounted. Before mounting, you need to associate the network on the resource pool network management page. It can be used in multiple environments and can be shared among multiple development and training environments. It works well for exploratory tasks and experiments but struggles with heavy I/O operations.

Constraints

No constraints

Debugging

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

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

POST /v1/{project_id}/notebooks/{instance_id}/storage

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
instance_id	Yes	String	Definition: Notebook instance ID. The ID is in the format of a Universally Unique Identifier (UUID). For details about how to obtain the ID, see Querying Notebook Instances. Constraints: N/A Range: N/A Default Value: N/A
project_id	Yes	String	Definition: Project ID. For details, see Obtaining a Project ID and Name. Constraints: N/A Range: N/A Default Value: N/A

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
category	Yes	String	Definition: Storage type for dynamic mounting. Constraints: N/A Range OBS OBSFS: parallel file system (PFS) EFS: SFS Turbo Default Value: None
mount_path	Yes	String	Definition: Path mounted to the notebook instance. Constraints: The value must be a subdirectory of the /data directory. Range: The value can contain at most 256 characters and must be in the /data/ subdirectory of the notebook instance. Default Value: None
uri	Yes	String	Definition: Storage path, for example, obs://modelarts/notebook/ or da669f6e-5591-4c10-b2a7-18d053a75677.sfsturbo.internal:/notebook. Constraints: The value must be a valid mount path in PFS or SFS Turbo. Range: The value can contain at most 256 characters. Default Value: N/A
efs_id	No	String	Definition: SFS Turbo instance ID. Constraints: This parameter is mandatory if category is set to EFS. Value Range: The value is a valid UUID. Default Value: None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
category	String	Definition: Storage type. The value can be OBS, OBSFS, or EFS. Range: N/A
id	String	Definition: ID of the dynamically mounted instance. Range: N/A
mount_path	String	Definition: Path mounted to the notebook instance. Range: N/A
status	String	Definition: Dynamic mounting status. Range MOUNTING: being mounted MOUNT_FAILED: mounting failed MOUNTED: mounted UNMOUNTING: being unmounted UNMOUNT_FAILED: unmounting failed UNMOUNTED: unmounted
uri	String	Definition: Storage path. Range: N/A
failure_reason	String	Definition: Mounting failure cause. This parameter is returned when the dynamic mounting status is MOUNT_FAILED. Range: N/A
efs_id	String	Definition: EFS storage instance ID. Range: N/A
mount_type	String	Definition: Storage mount type. Range: The value can be: STATIC: Storage cannot be mounted or unmounted when the instance is running. DYNAMIC: Storage can be mounted and unmounted when the instance is running.

Status code: 201

Created

Example Requests

Dynamically mount a PFS file system. Mount the /dir/to/mount/ directory in the pfs-name PFS to the specified file directory /data/mnt/pfs/ in the instance.

POST /v1/{project_id}/notebooks/{instance_id}/storage

{
  "category" : "OBSFS",
  "mount_path" : "/data/mnt/pfs/",
  "uri" : "obs://pfs-name/dir/to/mount/"
}

Dynamically mount an SFS Turbo file system. Mount the /dir/to/mount/ directory in the efa18c35-72f1-48a3-b2f7-7615da361f1a SFS Turbo file system to the specified file directory /data/mnt/efs/ in the instance.

POST /v1/{project_id}/notebooks/{instance_id}/storage

{
  "category" : "EFS",
  "mount_path" : "/data/mnt/efs/",
  "uri" : "efa18c35-72f1-48a3-b2f7-7615da361f1a.sfsturbo.internal:/dir/to/mount/",
  "efs_id" : "efa18c35-72f1-48a3-b2f7-7615da361f1a"
}

Example Responses

Status code: 200

{
  "id" : "91dd2d3f-2d92-475f-a375-04636af26cc9",
  "category" : "OBSFS",
  "mount_path" : "/data/mnt/pfs/",
  "uri" : "obs://pfs-name/dir/to/mount/",
  "status" : "MOUNTING"
}