huawei-cloud-modelarts-resource-pool-management

Huawei Cloud ModelArts 资源池管理

通过 hcloud CLI 对 ModelArts 专属资源池和节点池进行全生命周期管理，涵盖 10 个功能领域中的 53 项操作。

---

概述

此技能支持用户通过 hcloud CLI 管理 Huawei Cloud ModelArts 专属资源池（专属资源池）和节点池。涵盖完整生命周期，包括资源池 CRUD、节点管理、节点池管理、网络资源、标签管理、插件管理、工作负载、计划事件、操作系统配置和资源规格查询。对于需要收费的操作，还提供 BSS 价格查询。

架构

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

适用场景

• 资源池管理：创建、列出、查看、更新和删除资源池；监控、统计、节点配置和订单管理
• 资源池节点管理：列出／查看节点；批量删除、更新、锁定、解锁、重启、重置、调整规格、迁移和绑定
• 节点池管理：在资源池内创建、列出、查看、更新和删除节点池
• 网络资源：创建、列出、查看、更新和删除 ModelArts 网络；查询可用 IP
• 标签管理：列出、查看、批量创建和批量删除资源池标签
• 插件管理：列出插件模板；列出和创建资源池插件
• 作业和工作负载：列出工作负载、查看工作负载统计信息、列出作业
• 计划事件：列出并接受计划事件
• 操作系统配置：查看操作系统用户配置和配额
• 资源规格和事件：列出资源规格、事件和节点配置模板

---

前提条件

1. hcloud CLI 已安装并完成身份验证——参考：https://support.huaweicloud.com/qs-hcli/hcli_02_003.html
2. 已通过 hcloud 配置 Huawei Cloud AK/SK（参见下方的安全与凭证检查）
3. 已在目标区域启用 ModelArts 服务
4. IAM 权限——参见 references/iam-policies.md

安全与凭证检查

⚠️ 严重：本节定义了 Agent 的安全边界。请严格遵循。

🔒 安全规则（必须遵守）

• 🚫 绝不读取、回显或打印 AK/SK 值（例如，禁止执行 cat ~/.hcloud/config.json 或 echo $HW_ACCESS_KEY）
• 🚫 绝不读取或使用 cat 查看凭证文件，例如 ~/.hcloud/config.json 或任何可能包含机密信息的文件
• 🚫 绝不要求用户在对话或命令行中直接输入 AK/SK
• 🚫 绝不执行 hcloud configure set --cli-access-key=... --cli-secret-key=...——凭证配置由用户负责，应在 Agent 会话之外完成
• 🚫 绝不在每次 API 调用时传入 --cli-access-key／--cli-secret-key——在整个请求期间，这些值都会暴露在进程列表（ps aux）中
• ✅ 始终使用 hcloud configure list 检查凭证状态（仅检查是否存在，不读取值）
• ✅ 如果不存在有效配置文件，请停止操作，并指导用户在本会话之外配置凭证
• ✅ 建议使用权限最小化的 IAM 用户，而非主账号

✅ Agent 凭证检查（唯一可接受的检查）

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

• ✅ 预期结果：显示有效的配置文件，且 mode: AKSK

• ❌ 如果为空或无效 → 按照以下 3 步流程引导用户：

  分步指南（可复制粘贴给用户）：

  “未找到有效凭证。请在终端中按照以下 3 个步骤操作：”

  ① 获取 AK/SK 登录 Huawei Cloud 控制台 → IAM → Access Keys。如果没有，请点击“Create Access Key”并妥善保存。

  ② 在终端中运行以下命令（一次性设置）：

  hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>
  

  （将 <YOUR_AK> 和 <YOUR_SK> 替换为步骤 ① 中的值）

  ③ 完成后告诉我“configured”，我会验证是否生效。

  注意：configure set 命令会将凭证存储在 ~/.hcloud/config.json 中。此后，所有 hcloud 命令都会自动使用这些凭证，无需再次传入 AK/SK。

  Agent：请勿自行执行任何 configure set 命令。

🔧 用户的职责（用于说明文档，而非由 Agent 执行）

用户需在 Agent 会话之外（在自己的终端中）配置凭证：

# 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>

⚠️ 注意：hcloud CLI 不会读取 HW_ACCESS_KEY/HW_SECRET_KEY 环境变量（这些变量仅用于 Python SDK）。hcloud configure set 是唯一受支持的凭证配置方法。

---

工作流

步骤 1：确定操作

根据用户的请求，判断他们需要执行哪种资源池操作：

用户意图	操作类别
创建/列出/显示/更新/删除资源池	资源池管理
列出/显示/批量操作池节点	池节点管理
创建/列出/显示/更新/删除节点池	节点池管理
创建/列出/显示/更新/删除网络	网络资源
列出/显示/创建/删除池标签	标签管理
列出/创建插件	插件管理
列出工作负载、显示统计信息	作业和工作负载
列出/接受计划事件	计划事件
显示操作系统配置/配额	操作系统配置
列出规格、事件/模板	资源规格和事件

步骤 2：执行 CLI 命令

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

{region} 必须替换为实际区域，例如 cn-north-4。请勿将区域硬编码。

步骤 2.5：⚠️ 执行前检查（写操作必做）

执行任何写操作（创建/更新/删除/补丁/批量操作/接受）之前，你必须：

1. 阅读 references/known-issues.md — 查阅与目标 API 相关的章节
2. 检查该文件末尾的执行前检查清单 — 确认所有条件均已满足
3. 应用文档中记录的变通方法 — 尤其是以下高风险操作：

操作	关键问题	必须采取的措施
PatchPool、PatchNetwork、PatchNodePool	Content-Type 必须为 application/merge-patch+json	在标头部分使用 --cli-jsonInput
BatchUpdatePoolNodes	--action 的取值并非 true/false	使用字符串形式的 action 和 --cli-jsonInput
CreatePool	网络名称必须包含项目 ID 后缀	查询 ListNetworks 以获取准确名称
CreateNodePool	count ≥ 1，maxCount ≤ count	执行前验证约束条件
ShowNetworkAvailableIp	network_id 来自 status.subnets[0].networkId	先查询 ShowNetwork
ListEvents	--resource 必须为 pools（复数形式）	使用复数形式
BatchResetPoolNodes	VM 池不支持 strategy	已知限制，告知用户
BatchResizePoolNodes	仅支持 hyperinstance 节点	已知限制，告知用户
DeleteNetwork	如果网络正被池使用，则会失败	先删除池

**跳过此步骤会导致本可避免的失败。**表中的每个问题都是通过真实 API 测试发现的。

第 3 步：处理写操作

对于所有写操作（创建/更新/删除/修补/批量操作/接受），执行前都要征求用户确认。对于收费操作（CreatePool、CreateNodePool、PatchNodePool、BatchResizePoolNodes、CreateOrderId），先查询 BSS 定价，以便告知用户费用。定价查询工作流请参阅 references/pricing-inquiry.md。

---

KooCLI 命令格式标准

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

特性	描述	示例
服务名称	固定为：ModelArts	ModelArts
操作名称	PascalCase	ListPools、CreatePool
区域参数	--cli-region={region}	--cli-region=cn-north-4
简单参数	--key=value	--pool_name=xxx
索引参数	--key.1=value1	--node_name.1=node1
project_id	若省略则自动解析	使用已配置的项目 ID

注意：若省略 --project_id，系统会根据身份验证凭据自动解析。只有在指定特定项目时才需显式添加。

复杂参数：对于复杂的嵌套参数（例如 metadata、spec），请使用 --cli-jsonInput=/path/to/file.json。JSON 文件必须使用 {"body": {...}} 封装请求体。

---

核心命令

所有 10 个功能领域的 53 个 CLI 命令示例均记录在单独的参考文件中。

📖 有关详细的命令语法、参数和示例，请阅读 references/cli-command-examples.md

快速索引

#	领域	API	关键操作
1	资源池管理	11	ListPools、ShowPool、CreatePool、PatchPool、DeletePool、ShowPoolMonitor/Statistics/RuntimeMetrics/NodeConfig、CreateOrderId、ShowOrder
2	池节点管理	11	ListPoolNodes、ShowPoolNode、BatchDelete/Update/Lock/Unlock/Reboot/Reset/Resize/Migrate/Bind
3	节点池管理	6	ListNodePools、ShowNodePool、CreateNodePool、PatchNodePool、DeleteNodePool、ListNodePoolNodes
4	网络资源	6	ListNetworks、ShowNetwork、CreateNetwork、PatchNetwork、DeleteNetwork、ShowNetworkAvailableIp
5	标签管理	4	ListPoolTags、ShowPoolTags、BatchCreatePoolTags、BatchDeletePoolTags
6	插件管理	4	ListPluginTemplates、ShowPluginTemplate、ListPoolPlugins、CreatePoolPlugin
7	作业与工作负载	3	ListWorkloads、ShowWorkloadStatistics、ListJobs
8	计划事件	2	ListScheduledEvents、AcceptScheduledEvent
9	OS 配置	2	ShowOsConfig、ShowOsQuota
10	资源规格与事件	4	ListResourceFlavors、ListEvents、ShowNodeConfigTemplate、ShowPoolNodeConfigTemplate

执行任何命令时，务必查阅参考文件，以确认准确的参数名称、必填/可选标记及用法。

---

参数确认

参数	必填	描述	示例
{region}	是	华为云区域	cn-north-4、cn-east-2
{pool_name}	池操作	资源池名称	my-resource-pool
{node_name}	节点操作	池节点名称	node-xxx
{nodepool_name}	NodePool 操作	节点池名称	my-nodepool
{network_name}	网络操作	网络名称	my-network
{flavor_id}	创建/调整大小	资源规格 ID	modelarts.vm.cpu.16u64g.d
{project_id}	否（自动）	项目 ID，若省略则自动解析	默认情况下可省略
{order_name}	ShowOrder	订单名称	order-xxx

---

SDK 回退

如果 CLI 操作因 CLI 错误而失败，请回退到 SDK：

from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkmodelarts.v2.modelarts_client import ModelArtsClient
from huaweicloudsdkmodelarts.v2.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()

---

参考文档

文档	说明
references/cli-command-examples.md	全部 53 个 API 的详细 CLI 命令语法和示例
references/api-paths.md	SDK 源码中的 REST API 路径
references/iam-policies.md	最小权限 IAM 策略
references/known-issues.md	已知问题及解决方法
references/pricing-inquiry.md	可计费操作的 BSS 价格查询指南
references/verification-method.md	验证和测试方法
references/dataflow-diagram.md	Mermaid 数据流图
references/acceptance-criteria.md	验收标准清单
references/cli-installation-guide.md	CLI 安装和身份验证指南

---

已知问题摘要

⚠️ 在执行任何写入操作之前，请先阅读 references/known-issues.md。 以下所有问题均已通过真实 API 测试验证。

严重问题（会导致立即失败）：

• PATCH 操作（PatchPool/PatchNetwork/PatchNodePool）：必须使用 --cli-jsonInput，并设置 Content-Type: application/merge-patch+json 标头
• BatchUpdatePoolNodes：--action 的取值为 openHaRedundant/closeHaRedundant/createTags/deleteTags，而非 true/false；请使用 --cli-jsonInput
• CreatePool：网络名称必须包含项目 ID 后缀；池类型为 Dedicate（末尾没有 d）
• CreateNodePool：count 必须 ≥ 1；maxCount 必须 ≤ count
• ShowNetworkAvailableIp：--network_id 必须取自 status.subnets[0].networkId，而非 spec.subnets[0].id
• ListEvents：--resource 必须为 pools（复数），而非 pool

已知 API 限制：

• BatchResetPoolNodes：VM 池的 rollingConfig.strategy 没有有效取值
• BatchResizePoolNodes：仅支持超节点扩容，不支持常规 VM 节点
• BatchMigratePoolNodes：源集群名称和目标集群名称必须不同
• DeleteNetwork：如果网络正在被资源池使用，则删除会失败（请先删除资源池）

数据字段位置：

• 节点标签：metadata.annotations["os.modelarts/tms.tags"]（JSON 字符串，而非 metadata.labels）
• 节点锁定状态：metadata.annotations["os.modelarts.node/lock.action"]

完整详情、解决方法和预检清单请参阅 references/known-issues.md。

---

说明

• 所有写入操作（Create/Update/Delete/Patch/Batch/Accept）都必须在执行前获得用户确认
• 可计费操作（CreatePool、CreateNodePool、PatchNodePool、BatchResizePoolNodes、CreateOrderId）必须先查询 BSS 价格，并在执行前告知用户费用
• 区域不使用硬编码值，而是使用 {region} 占位符
• 如未提供 project_id，系统会自动解析
• 任何文件中都不包含硬编码的 AK/SK——用户需在 Agent 会话之外通过 hcloud configure set 配置凭证
• Agent 只能使用 hcloud configure list 检查凭证是否存在——绝不可读取或回显 AK/SK 值
• 如果未找到有效凭证，Agent 必须停止操作，并指导用户完成 3 步配置流程（请参阅先决条件部分）
• CLI 遇到问题时，可使用 SDK 作为备用方案
• 复杂的嵌套参数需使用 --cli-jsonInput 并配合 JSON 文件