Imported from huaweicloud/huaweicloud-skills (skills/ai/modelarts/huawei-cloud-modelarts-notebook-management/SKILL.md). Install upstream with npx skills add huaweicloud/huaweicloud-skills --skill huawei-cloud-modelarts-notebook-management. Copyright stays with the author.

Huawei Cloud ModelArts Notebook Management

Full lifecycle management for ModelArts Notebook instances via hcloud CLI — 31 API interfaces across 7 functional domains.

Overview

This skill enables users to manage Huawei Cloud ModelArts Notebook instances through the hcloud CLI. It covers the complete notebook lifecycle including instance CRUD, start/stop, lease renewal, tag management, image management, flavor/cluster queries, feature queries, and dynamic storage management.

Architecture

User Request → Agent → hcloud ModelArts <Operation> --cli-region={region} [--params] → Huawei Cloud ModelArts API

Applicable Scenarios

Daily Operations: List notebooks, check status, view details, query flavors
Instance Lifecycle: Create, start, stop, update, delete notebook instances
Image Management: Save running instance as image, register/list/delete/sync custom images
Storage Management: Dynamically attach/detach storage to notebook instances
Lease Management: Query and renew notebook leases
Tag Management: Create, delete, query notebook tags

Scope

本 skill 仅支持 ModelArts Notebook 实例管理（31 个 API），涵盖上述 7 个功能域。

不支持以下 ModelArts 能力，相关请求请使用对应 skill：

推理服务（在线服务、批量服务）— 使用推理服务管理 skill
DevServer（开发环境）— 使用 DevServer 管理 skill
模型管理（导入/导出/发布模型）— 使用模型管理 skill
训练作业（创建/管理训练任务）— 使用训练作业管理 skill
自动搜索、超参调优 — 使用自动搜索 skill

Prerequisites

hcloud CLI installed and authenticated — Reference: https://support.huaweicloud.com/qs-hcli/hcli_02_003.html
Huawei Cloud AK/SK configured via hcloud (see Security & Credential Check below)
ModelArts service enabled in the target region
IAM permissions — See references/iam-policies.md

Security & Credential Check

⚠️ CRITICAL: This section defines the agent's security boundary. Follow it strictly.

🔒 Security Rules (MANDATORY)

🚫 NEVER read, echo, or print AK/SK values (e.g., cat ~/.hcloud/config.json, echo $HW_ACCESS_KEY is FORBIDDEN)
🚫 NEVER read or cat credential files such as ~/.hcloud/config.json or any file that may contain secrets
🚫 NEVER ask the user to input AK/SK directly in the conversation or command line
🚫 NEVER execute hcloud configure set --cli-access-key=... --cli-secret-key=... — credential configuration is the user's responsibility, done outside the agent session
🚫 NEVER pass --cli-access-key/--cli-secret-key on every API call — they will be exposed in process listings (ps aux) for the entire request duration
✅ ALWAYS use hcloud configure list to check credential status (presence check only, not values)
✅ If no valid profile exists, STOP and instruct the user to configure credentials outside this session
✅ Recommend using IAM user with minimal permissions instead of main account

✅ Agent Credential Check (the ONLY acceptable check)

# Step 1: Check credential status — presence only, not values
hcloud configure list

✅ Expected: Shows a valid profile with mode: AKSK
❌ If empty/invalid → Guide the user with the 3-step process below:

Step-by-step guidance (copy-paste for the user):
"No valid credentials found. Please follow these 3 steps in your terminal:"

① Get your AK/SK Log in to Huawei Cloud Console → IAM → Access Keys. If you don't have one, click "Create Access Key" and save it securely.

② Run this in your terminal (one-time setup):
```
hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>
```
(Replace <YOUR_AK> and <YOUR_SK> with the values from step ①)

③ Come back and tell me "configured", I'll verify it works.

Note: The configure set command stores your credentials in ~/.hcloud/config.json. After that, all hcloud commands use them automatically — no need to pass AK/SK again.

Agent: DO NOT execute any configure set command yourself.

🔧 User's Responsibility (for documentation, NOT agent execution)

The user configures credentials outside the agent session (in their own terminal):

# One-time setup — run this in your terminal, NOT in the agent chat
HISTCONTROL=ignorespace
 hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>

⚠️ Note: hcloud CLI does NOT read HW_ACCESS_KEY/HW_SECRET_KEY environment variables (those are for Python SDK only). hcloud configure set is the only supported credential configuration method.

Workflow

Step 1: Identify the Operation

Determine which notebook operation the user needs based on their request:

User Intent	Operation Category
Create/list/view/update/delete/start/stop notebook	Instance Management
Query/renew lease	Lease Management
Create/delete/query tags	Tag Management
Save/register/list/delete/sync image	Image Management
Query flavors/clusters/features	Flavor & Cluster
Attach/detach/list storage	Dynamic Storage

Step 2: Execute CLI Command

hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]

{region} must be replaced with the actual region, e.g., cn-north-4. Do NOT hardcode the region.

Step 2.5: Consult Known Issues (Write Operations Only)

Before executing any write operation, read references/known-issues.md and check for known pitfalls, parameter corrections, and required workarounds for the target API.

Common workarounds to apply:

API	Issue	Workaround
CreateNotebook (EVS)	CLI rejects `--volume.category=EVS`	Use `--cli-jsonInput` with `{"body":{...}}` wrapper + explicit `--project_id`
CreateNotebook	Param name `flavor_id` wrong	Use `--flavor`
CreateNotebook	Param name `volume.size` wrong	Use `--volume.capacity`
CreateNotebook	`ownership=PRIVATE` invalid	Use `MANAGED` or `DEDICATED`
AttachDynamicStorage	STOPPED instance rejected	Ensure instance is `RUNNING`
AttachDynamicStorage	`mount_path` format	Must start with `/data/` and end with `/`
RegisterImage	`arch` case mismatch	Use uppercase `X86_64`/`AARCH64`
RenewLease	`type` case mismatch	Use lowercase `timing`/`idle`

This step is mandatory for all write operations. Skipping it may result in CLI parameter errors or API failures that are already documented.

Step 3: Handle Write Operations

For all write operations (Create/Update/Delete/Start/Stop/Attach/Detach/Register/Sync/Renew), prompt the user for confirmation before execution. For chargeable operations (CreateNotebook, StartNotebook), inquire BSS pricing first to inform the user of costs. See references/pricing-inquiry.md for the pricing inquiry workflow.

删除类操作交互指引：当用户请求删除标签（DeleteNotebookTags）、删除镜像分组（DeleteImageGroup）等操作但未指定具体对象时，必须先查询当前对象列表（如 ShowNotebookTags / ListImageGroup），向用户展示并确认要删除哪个对象，确认后再执行。避免因上下文不明确导致误删。

KooCLI Command Format Standard

hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]

Feature	Description	Example
Service name	Fixed: `ModelArts`	`ModelArts`
Operation name	PascalCase	`ListNotebooks`, `CreateNotebook`
Region parameter	`--cli-region={region}`	`--cli-region=cn-north-4`
Simple parameter	`--key=value`	`--id=xxx`
Indexed parameter	`--key.1=value1`	`--tags.1.key=env`
project_id	Auto-resolved if omitted	Uses configured project ID

Note: --project_id is auto-resolved from authentication credentials if omitted. Include it explicitly only when targeting a specific project.

Core Commands

All 31 CLI command examples across 7 functional domains are documented in a separate reference file.

📖 For detailed command syntax, parameters, and examples, read references/cli-command-examples.md

Quick Index

#	Domain	APIs	Key Operations
1	Instance Management	8	CreateNotebook, ListNotebooks, ListAllNotebooks, ShowNotebook, UpdateNotebook, DeleteNotebook, StartNotebook, StopNotebook
2	Lease Management	2	ShowLease, RenewLease
3	Tag Management	3	ShowNotebookTags, CreateNotebookTags, DeleteNotebookTags
4	Image Management	9	CreateImage, ListImage, RegisterImage, ShowImage, DeleteImage, SyncImage, ListImageGroup, DeleteImageGroup, UpdateImageGroup
5	Flavor and Cluster	4	ListFlavors, ShowSwitchableFlavors, ListAuthoringClusters, ShowCluster
6	Feature Query	1	ListFeatures
7	Dynamic Storage	4	ListDynamicStorages, AttachDynamicStorage, ShowDynamicStorage, DetachDynamicStorage

When executing any command, always refer to the reference file for exact parameter names, required/optional flags, and usage patterns.

Parameter Confirmation

Parameter	Required	Description	Example
`{region}`	Yes	Huawei Cloud region	`cn-north-4`, `cn-east-3`
`{instance_id}`	Yes (most ops)	Notebook instance UUID	`xxx-xxx-xxx`
`{image_id}`	Create/List	Image UUID	`xxx-xxx-xxx`
`{flavor_id}`	Create	Flavor ID for instance	`modelarts.bm.4xlarge.pro`
`{resource_id}`	Tag ops	Resource ID for tagging	`xxx-xxx-xxx`
`{cluster_id}`	ShowCluster	Cluster ID	`xxx-xxx-xxx`
`{storage_id}`	Storage ops	Storage ID	`xxx-xxx-xxx`
`{feature}`	ListFeatures	Feature name	`NOTEBOOK`
`{project_id}`	No (auto)	Project ID, auto-resolved if omitted	Omit for default

SDK Fallback

If a CLI operation fails due to a CLI bug, fall back to SDK:

from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkmodelarts.v1.modelarts_client import ModelArtsClient
from huaweicloudsdkmodelarts.v1.region.modelarts_region import ModelArtsRegion

credentials = BasicCredentials(ak="{AK}", sk="{SK}", project_id="{project_id}")
client = ModelArtsClient.new_builder() \
    .with_credentials(credentials) \
    .with_region(ModelArtsRegion.value_of("{region}")) \
    .build()

Reference Documents

Document	Description
references/cli-command-examples.md	Detailed CLI command syntax and examples for all 31 APIs
references/iam-policies.md	Least-privilege IAM policies
references/verification-method.md	Verification and testing methods
references/dataflow-diagram.md	Mermaid data flow diagram
references/acceptance-criteria.md	Acceptance criteria checklist
references/api-paths.md	REST API paths from SDK source
references/cli-installation-guide.md	CLI installation and authentication guide
references/known-issues.md	Known issues and workarounds
references/pricing-inquiry.md	BSS pricing inquiry guide for chargeable operations

Known Issues (Summary)

Full details: references/known-issues.md

#	Issue	Key Takeaway
1	CLI omits EVS from `volume.category` enum	Use `--cli-jsonInput` with `body` wrapper + explicit `--project_id`
2	Storage category × ownership matrix	EVS:MANAGED ✅, OBS/OBSFS:DEDICATED ✅, OBS/OBSFS:MANAGED ❌
3	DEDICATED ownership requires `pool_id`	Query dedicated pools first, pass top-level `pool_id`
4	OBS as `data_volume` silently fails	Use OBS as main `volume` or use OBSFS as `data_volume`
5	Bucket type (POSIX vs OBJECT) irrelevant	Both work with DEDICATED ownership
6	OBSFS:MANAGED extended storage unsupported	Use DEDICATED for OBSFS
7	OBS/OBSFS main volume needs `dew_secret_name`	Store AK/SK in DEW/CSMS secret
8	OBS data volume requires `mount_path`	Always specify valid path
9	Image/flavor architecture mismatch	Match `arch` field between image and flavor
10	`--cli-jsonInput` general workaround	Must wrap in `{"body":{...}}` + pass `--project_id` explicitly
11	`ShowLease` duration is total, not remaining	Calculate: `remaining = (create_at + duration) - current_time`
12	`ListImageGroup` response field varies with `--limit`	Without limit: `groups` field; with limit: `data` field. Parse both
13	`AttachDynamicStorage` only supports POSIX buckets	OBJECT buckets rejected with `ModelArts.6772`; use `obsutil stat` to verify

Notes

All 31 API interfaces are available via hcloud ModelArts CLI
SDK fallback available via huaweicloudsdkmodelarts v1 if CLI encounters issues
Region is specified via --cli-region and should NOT be hardcoded
--project_id is auto-resolved from credentials if omitted (but must be explicit when using --cli-jsonInput)
All write operations (Create/Update/Delete/Start/Stop/Attach/Detach/Register/Sync/Renew) require user confirmation before execution
Chargeable operations (CreateNotebook, StartNotebook) require BSS pricing inquiry to inform users of costs before execution
API paths verified from SDK source _http_info resource_path — no inferred endpoints
No hardcoded AK/SK in any file — credentials managed by hcloud via hcloud configure list/set

huawei-cloud-modelarts-notebook-management

About