huawei-cloud-modelarts-notebook-management
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseHuawei Cloud ModelArts Notebook Management
华为云ModelArts Notebook管理
Full lifecycle management for ModelArts Notebook instances via hcloud CLI — 31 API interfaces across 7 functional domains.
通过hcloud CLI实现ModelArts Notebook实例的全生命周期管理——覆盖7个功能域的31个API接口。
Overview
概述
This skill enables users to manage Huawei Cloud ModelArts Notebook instances through the 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.
hcloud本skill支持用户通过 CLI管理华为云ModelArts Notebook实例,涵盖Notebook的完整生命周期管理,包括实例的CRUD(创建/读取/更新/删除)、启动/停止、租期续费、标签管理、镜像管理、规格/集群查询、特性查询以及动态存储管理。
hcloudArchitecture
架构
User Request → Agent → hcloud ModelArts <Operation> --cli-region={region} [--params] → Huawei Cloud ModelArts APIUser Request → Agent → hcloud ModelArts <Operation> --cli-region={region} [--params] → Huawei Cloud ModelArts APIApplicable 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
- 日常运维:列出Notebook、检查状态、查看详情、查询规格
- 实例生命周期:创建、启动、停止、更新、删除Notebook实例
- 镜像管理:将运行中实例保存为镜像、注册/列出/删除/同步自定义镜像
- 存储管理:为Notebook实例动态挂载/卸载存储
- 租期管理:查询和续费Notebook租期
- 标签管理:创建、删除、查询Notebook标签
Scope
范围
本 skill 仅支持 ModelArts Notebook 实例管理(31 个 API),涵盖上述 7 个功能域。
不支持以下 ModelArts 能力,相关请求请使用对应 skill:
- 推理服务(在线服务、批量服务)— 使用推理服务管理 skill
- DevServer(开发环境)— 使用 DevServer 管理 skill
- 模型管理(导入/导出/发布模型)— 使用模型管理 skill
- 训练作业(创建/管理训练任务)— 使用训练作业管理 skill
- 自动搜索、超参调优 — 使用自动搜索 skill
本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
- 已安装并认证hcloud CLI — 参考文档:https://support.huaweicloud.com/qs-hcli/hcli_02_003.html
- 已通过hcloud配置华为云AK/SK(详见下方安全与凭证检查)
- 目标区域已启用ModelArts服务
- 具备IAM权限 — 参见references/iam-policies.md
Security & Credential Check
安全与凭证检查
⚠️ CRITICAL: This section defines the agent's security boundary. Follow it strictly.
⚠️ 重要:本章节定义了Agent的安全边界,请严格遵守。
🔒 Security Rules (MANDATORY)
🔒 安全规则(强制要求)
- 🚫 NEVER read, echo, or print AK/SK values (e.g., ,
cat ~/.hcloud/config.jsonis FORBIDDEN)echo $HW_ACCESS_KEY - 🚫 NEVER read or cat credential files such as or any file that may contain secrets
~/.hcloud/config.json - 🚫 NEVER ask the user to input AK/SK directly in the conversation or command line
- 🚫 NEVER execute — credential configuration is the user's responsibility, done outside the agent session
hcloud configure set --cli-access-key=... --cli-secret-key=... - 🚫 NEVER pass /
--cli-access-keyon every API call — they will be exposed in process listings (--cli-secret-key) for the entire request durationps aux - ✅ ALWAYS use to check credential status (presence check only, not values)
hcloud configure list - ✅ 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
- 🚫 禁止读取、回显或打印AK/SK值(例如、
cat ~/.hcloud/config.json均为禁止操作)echo $HW_ACCESS_KEY - 🚫 禁止读取或显示凭证文件,如或任何可能包含密钥的文件
~/.hcloud/config.json - 🚫 禁止要求用户在对话或命令行中直接输入AK/SK
- 🚫 禁止执行— 凭证配置是用户的责任,需在Agent会话外完成
hcloud configure set --cli-access-key=... --cli-secret-key=... - 🚫 禁止在每次API调用中传递/
--cli-access-key— 这些参数会在请求全程暴露于进程列表(--cli-secret-key)中ps aux - ✅ 必须使用检查凭证状态(仅检查是否存在,不查看具体值)
hcloud configure list - ✅ 如果没有有效配置文件,立即停止并指导用户在本会话外配置凭证
- ✅ 推荐使用权限最小化的IAM用户而非主账号
✅ Agent Credential Check (the ONLY acceptable check)
✅ Agent凭证检查(唯一可接受的检查方式)
bash
undefinedbash
undefinedStep 1: Check credential status — presence only, not values
步骤1:检查凭证状态 — 仅确认存在性,不查看具体值
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](https://console.huaweicloud.com) → 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):**
> ```bash
> 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.*hcloud configure list
- ✅ **预期结果**:显示一个有效的配置文件,`mode: AKSK`
- ❌ **若为空/无效** → 按以下3步引导用户:
**分步指引(可直接复制给用户):**
> *"未找到有效凭证,请在终端中执行以下3步操作:"*
>
> **① 获取AK/SK**
> 登录[华为云控制台](https://console.huaweicloud.com) → IAM → 访问密钥。若没有密钥,点击"创建访问密钥"并安全保存。
>
> **② 在终端中执行以下命令(仅需配置一次):**
> ```bash
> hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>
> ```
> *(将`<YOUR_AK>`和`<YOUR_SK>`替换为步骤①中获取的值)*
>
> **③ 配置完成后告知我"已配置",我会验证是否生效。**
>
> *注意:`configure set`命令会将凭证存储在`~/.hcloud/config.json`中。之后所有hcloud命令都会自动使用该凭证,无需再次传递AK/SK。*
>
> *Agent注意:请勿自行执行任何`configure set`命令。*🔧 User's Responsibility (for documentation, NOT agent execution)
🔧 用户责任(仅用于文档说明,Agent无需执行)
The user configures credentials outside the agent session (in their own terminal):
bash
undefined用户需在Agent会话外(自己的终端中)配置凭证:
bash
undefinedOne-time setup — run this in your terminal, NOT in the agent chat
仅需配置一次 — 在你的终端中执行,不要在Agent聊天框中执行
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.
---HISTCONTROL=ignorespace
hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>
> ⚠️ **注意**:hcloud CLI **不支持**读取`HW_ACCESS_KEY`/`HW_SECRET_KEY`环境变量(这些变量仅适用于Python SDK)。唯一支持的凭证配置方式是`hcloud configure set`。
---Workflow
工作流程
Step 1: Identify the Operation
步骤1:确定操作类型
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 |
根据用户请求确定所需的Notebook操作:
| 用户意图 | 操作类别 |
|---|---|
| 创建/列出/查看/更新/删除/启动/停止Notebook | 实例管理 |
| 查询/续费租期 | 租期管理 |
| 创建/删除/查询标签 | 标签管理 |
| 保存/注册/列出/删除/同步镜像 | 镜像管理 |
| 查询规格/集群/特性 | 规格与集群 |
| 挂载/卸载/列出存储 | 动态存储 |
Step 2: Execute CLI Command
步骤2:执行CLI命令
bash
hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]must be replaced with the actual region, e.g.,{region}. Do NOT hardcode the region.cn-north-4
bash
hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]必须替换为实际区域,例如{region},请勿硬编码区域。cn-north-4
Step 2.5: Consult Known Issues (Write Operations Only)
步骤2.5:查阅已知问题(仅写入操作)
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 | Use |
| CreateNotebook | Param name | Use |
| CreateNotebook | Param name | Use |
| CreateNotebook | | Use |
| AttachDynamicStorage | STOPPED instance rejected | Ensure instance is |
| AttachDynamicStorage | | Must start with |
| RegisterImage | | Use uppercase |
| RenewLease | | Use lowercase |
This step is mandatory for all write operations. Skipping it may result in CLI parameter errors or API failures that are already documented.
在执行任何写入操作前,请阅读references/known-issues.md,检查目标API的已知问题、参数修正方案及所需的解决方法。
常见解决方法:
| API | 问题 | 解决方法 |
|---|---|---|
| CreateNotebook (EVS) | CLI拒绝 | 使用 |
| CreateNotebook | 参数名 | 使用 |
| CreateNotebook | 参数名 | 使用 |
| CreateNotebook | | 使用 |
| AttachDynamicStorage | 拒绝已停止的实例 | 确保实例处于 |
| AttachDynamicStorage | | 必须以 |
| RegisterImage | | 使用大写 |
| RenewLease | | 使用小写 |
本步骤对所有写入操作强制要求。跳过此步骤可能会导致CLI参数错误或已记录的API调用失败。
Step 3: Handle Write Operations
步骤3:处理写入操作
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
对于所有写入操作(创建/更新/删除/启动/停止/挂载/卸载/注册/同步/续费),执行前需提示用户确认。对于收费操作(CreateNotebook、StartNotebook),需先查询BSS定价,告知用户成本。定价查询流程参见references/pricing-inquiry.md。
删除类操作交互指引:当用户请求删除标签(DeleteNotebookTags)、删除镜像分组(DeleteImageGroup)等操作但未指定具体对象时,必须先查询当前对象列表(如/ShowNotebookTags),向用户展示并确认要删除的对象,确认后再执行。避免因上下文不明确导致误删。ListImageGroup
KooCLI Command Format Standard
KooCLI命令格式规范
bash
hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]| Feature | Description | Example |
|---|---|---|
| Service name | Fixed: | |
| Operation name | PascalCase | |
| Region parameter | | |
| Simple parameter | | |
| Indexed parameter | | |
| project_id | Auto-resolved if omitted | Uses configured project ID |
Note:is auto-resolved from authentication credentials if omitted. Include it explicitly only when targeting a specific project.--project_id
bash
hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]| 特性 | 说明 | 示例 |
|---|---|---|
| 服务名称 | 固定为 | |
| 操作名称 | 采用PascalCase命名 | |
| 区域参数 | | |
| 简单参数 | | |
| 索引参数 | | |
| project_id | 若省略则自动解析 | 使用已配置的项目ID |
注意:若省略,系统会从认证凭证中自动解析。仅当目标为特定项目时才需要显式传递。--project_id
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
7个功能域的全部31条CLI命令示例记录在单独的参考文档中。
📖 如需详细的命令语法、参数及示例,请阅读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.
| # | 功能域 | APIs | 核心操作 |
|---|---|---|---|
| 1 | 实例管理 | 8 | CreateNotebook, ListNotebooks, ListAllNotebooks, ShowNotebook, UpdateNotebook, DeleteNotebook, StartNotebook, StopNotebook |
| 2 | 租期管理 | 2 | ShowLease, RenewLease |
| 3 | 标签管理 | 3 | ShowNotebookTags, CreateNotebookTags, DeleteNotebookTags |
| 4 | 镜像管理 | 9 | CreateImage, ListImage, RegisterImage, ShowImage, DeleteImage, SyncImage, ListImageGroup, DeleteImageGroup, UpdateImageGroup |
| 5 | 规格与集群 | 4 | ListFlavors, ShowSwitchableFlavors, ListAuthoringClusters, ShowCluster |
| 6 | 特性查询 | 1 | ListFeatures |
| 7 | 动态存储 | 4 | ListDynamicStorages, AttachDynamicStorage, ShowDynamicStorage, DetachDynamicStorage |
执行任何命令时,请务必参考参考文档获取准确的参数名称、必填/可选标志及使用方式。
Parameter Confirmation
参数确认
| Parameter | Required | Description | Example |
|---|---|---|---|
| Yes | Huawei Cloud region | |
| Yes (most ops) | Notebook instance UUID | |
| Create/List | Image UUID | |
| Create | Flavor ID for instance | |
| Tag ops | Resource ID for tagging | |
| ShowCluster | Cluster ID | |
| Storage ops | Storage ID | |
| ListFeatures | Feature name | |
| No (auto) | Project ID, auto-resolved if omitted | Omit for default |
| 参数 | 是否必填 | 说明 | 示例 |
|---|---|---|---|
| 是 | 华为云区域 | |
| 是(多数操作) | Notebook实例UUID | |
| 创建/列出操作 | 镜像UUID | |
| 创建操作 | 实例规格ID | |
| 标签操作 | 用于打标签的资源ID | |
| 查看集群操作 | 集群ID | |
| 存储操作 | 存储ID | |
| 特性查询操作 | 特性名称 | |
| 否(自动解析) | 项目ID,省略则自动解析 | 默认省略 |
SDK Fallback
SDK fallback方案
If a CLI operation fails due to a CLI bug, fall back to SDK:
python
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()若CLI操作因CLI bug失败,可 fallback至SDK:
python
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 |
| 文档 | 说明 |
|---|---|
| references/cli-command-examples.md | 所有31个API的详细CLI命令语法及示例 |
| references/iam-policies.md | 最小权限IAM策略 |
| references/verification-method.md | 验证与测试方法 |
| references/dataflow-diagram.md | Mermaid数据流图 |
| references/acceptance-criteria.md | 验收标准 checklist |
| references/api-paths.md | 来自SDK源码的REST API路径 |
| references/cli-installation-guide.md | CLI安装与认证指南 |
| references/known-issues.md | 已知问题及解决方法 |
| references/pricing-inquiry.md | 收费操作的BSS定价查询指南 |
Known Issues (Summary)
已知问题(摘要)
Full details: references/known-issues.md
| # | Issue | Key Takeaway |
|---|---|---|
| 1 | CLI omits EVS from | Use |
| 2 | Storage category × ownership matrix | EVS:MANAGED ✅, OBS/OBSFS:DEDICATED ✅, OBS/OBSFS:MANAGED ❌ |
| 3 | DEDICATED ownership requires | Query dedicated pools first, pass top-level |
| 4 | OBS as | Use OBS as main |
| 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 | Store AK/SK in DEW/CSMS secret |
| 8 | OBS data volume requires | Always specify valid path |
| 9 | Image/flavor architecture mismatch | Match |
| 10 | | Must wrap in |
| 11 | | Calculate: |
| 12 | | Without limit: |
| 13 | | OBJECT buckets rejected with |
详细内容:references/known-issues.md
| # | 问题 | 关键要点 |
|---|---|---|
| 1 | CLI的 | 使用 |
| 2 | 存储类别与ownership矩阵 | EVS:MANAGED ✅, OBS/OBSFS:DEDICATED ✅, OBS/OBSFS:MANAGED ❌ |
| 3 | DEDICATED ownership需要 | 先查询专属资源池,传递顶级 |
| 4 | 将OBS作为 | 将OBS作为主 |
| 5 | Bucket类型(POSIX vs OBJECT)无关紧要 | 两者均适用于DEDICATED ownership |
| 6 | OBSFS:MANAGED扩展存储不被支持 | 对OBSFS使用DEDICATED |
| 7 | OBS/OBSFS主卷需要 | 将AK/SK存储在DEW/CSMS密钥中 |
| 8 | OBS数据卷需要 | 始终指定有效路径 |
| 9 | 镜像与规格架构不匹配 | 匹配镜像与规格的 |
| 10 | | 必须包裹在 |
| 11 | | 计算方式: |
| 12 | | 无limit时: |
| 13 | | OBJECT buckets会被拒绝,错误码 |
Notes
注意事项
- All 31 API interfaces are available via CLI
hcloud ModelArts - SDK fallback available via v1 if CLI encounters issues
huaweicloudsdkmodelarts - Region is specified via and should NOT be hardcoded
--cli-region - is auto-resolved from credentials if omitted (but must be explicit when using
--project_id)--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— no inferred endpointsresource_path - No hardcoded AK/SK in any file — credentials managed by hcloud via
hcloud configure list/set
- 所有31个API接口均可通过CLI调用
hcloud ModelArts - 若CLI出现问题,可通过v1版本的SDK进行fallback
huaweicloudsdkmodelarts - 区域通过指定,请勿硬编码
--cli-region - 若省略则从凭证自动解析(但使用
--project_id时必须显式传递)--cli-jsonInput - 所有写入操作(创建/更新/删除/启动/停止/挂载/卸载/注册/同步/续费)执行前需用户确认
- 收费操作(CreateNotebook、StartNotebook)执行前需查询BSS定价并告知用户成本
- API路径已通过SDK源码的
_http_info验证,无推断的端点resource_path - 所有文件中均无硬编码的AK/SK — 凭证通过hcloud的管理
hcloud configure list/set