huawei-cloud-modelarts-notebook-management

Huawei Cloud ModelArts Notebook 管理

hcloud CLI を使用して ModelArts Notebook インスタンスをライフサイクル全体にわたって管理します — 7 つの機能ドメインにまたがる 31 の API インターフェース。

---

概要

このスキルを使用すると、hcloud CLI を通じて Huawei Cloud ModelArts Notebook インスタンスを管理できます。インスタンスの CRUD、起動／停止、リースの更新、タグ管理、イメージ管理、フレーバー／クラスターの照会、機能の照会、動的ストレージ管理など、Notebook のライフサイクル全体をカバーします。

アーキテクチャ

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

対象シナリオ

• 日常運用：Notebook の一覧表示、ステータスの確認、詳細の表示、フレーバーの照会
• インスタンスのライフサイクル：Notebook インスタンスの作成、起動、停止、更新、削除
• イメージ管理：実行中のインスタンスをイメージとして保存、カスタムイメージの登録／一覧表示／削除／同期
• ストレージ管理：Notebook インスタンスへのストレージの動的な接続／切断
• リース管理：Notebook のリースの照会と更新
• タグ管理：Notebook タグの作成、削除、照会

対象範囲

このスキルは ModelArts Notebook インスタンス管理（31 個の API）のみをサポートし、上記の 7 つの機能ドメインをカバーします。

以下の ModelArts 機能はサポートしていません。関連するリクエストには、対応するスキルを使用してください。

• 推論サービス（オンラインサービス、バッチサービス）— 推論サービス管理スキルを使用
• DevServer（開発環境）— DevServer 管理スキルを使用
• モデル管理（モデルのインポート／エクスポート／公開）— モデル管理スキルを使用
• トレーニングジョブ（トレーニングタスクの作成／管理）— トレーニングジョブ管理スキルを使用
• 自動検索、ハイパーパラメーター調整 — 自動検索スキルを使用

---

前提条件

1. hcloud CLI がインストールされ、認証済みであること — 参照先：https://support.huaweicloud.com/qs-hcli/hcli_02_003.html
2. Huawei Cloud の AK/SK が hcloud を通じて設定されていること（以下の「セキュリティと認証情報の確認」を参照）
3. ModelArts サービス が対象リージョンで有効になっていること
4. IAM 権限 — references/iam-policies.md を参照

セキュリティと認証情報の確認

⚠️ 重大：このセクションでは、エージェントのセキュリティ境界を定義します。厳守してください。

🔒 セキュリティルール（必須）

• 🚫 AK/SK の値を読み取ったり、エコーしたり、表示したりすることは絶対にしないでください（例：cat ~/.hcloud/config.json、echo $HW_ACCESS_KEY は禁止です）
• 🚫 ~/.hcloud/config.json などの認証情報ファイルや、シークレットを含む可能性のあるファイルを読み取ったり、cat したりすることは絶対にしないでください
• 🚫 会話やコマンドラインで AK/SK を直接入力するようユーザーに求めることは絶対にしないでください
• 🚫 hcloud configure set --cli-access-key=... --cli-secret-key=... を実行することは絶対にしないでください — 認証情報の設定はユーザーの責任であり、エージェントのセッション外で行います
• 🚫 すべての API 呼び出しで --cli-access-key／--cli-secret-key を渡すことは絶対にしないでください — リクエストの処理中、プロセス一覧（ps aux）に値が露出します
• ✅ 認証情報のステータス確認には、必ず hcloud configure list を使用してください（値ではなく、設定の有無のみを確認します）
• ✅ 有効なプロファイルが存在しない場合は、停止して、このセッション外で認証情報を設定するようユーザーに案内してください
• ✅ メインアカウントではなく、最小限の権限を持つ IAM ユーザーの使用を推奨してください

✅ エージェントによる認証情報の確認（許可される唯一の確認方法）

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

• ✅ 期待される結果：mode: AKSK を含む有効なプロファイルが表示されます

• ❌ 空または無効な場合 → 以下の 3 ステップでユーザーに案内してください：

  手順（ユーザー向けにコピーして貼り付け可能）：

  「有効な認証情報が見つかりませんでした。ターミナルで以下の 3 ステップを実行してください：」

  ① AK/SK を取得する Huawei Cloud Console にログインし、IAM → アクセスキーに進みます。アクセスキーをお持ちでない場合は、「アクセスキーを作成」をクリックし、安全な場所に保存してください。

  ② ターミナルで次のコマンドを実行する（初回のみの設定）：

  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 を再度渡す必要はありません。

  エージェント：configure set コマンドは自分で実行しないでください。

🔧 ユーザーの責任（ドキュメント向けであり、エージェントによる実行向けではありません）

ユーザーは、エージェントセッションの外で（自身のターミナルで）認証情報を設定します。

# 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：既知の問題を確認する（書き込み操作のみ）

書き込み操作を実行する前に必ず、references/known-issues.md を読み、対象 API に関する既知の問題、パラメーターの修正、必要な回避策を確認してください。

適用する一般的な回避策：

API	問題	回避策
CreateNotebook（EVS）	CLI が --volume.category=EVS を拒否する	{"body":{...}} ラッパーと明示的な --project_id を指定して --cli-jsonInput を使用する
CreateNotebook	パラメーター名 flavor_id が誤っている	--flavor を使用する
CreateNotebook	パラメーター名 volume.size が誤っている	--volume.capacity を使用する
CreateNotebook	ownership=PRIVATE は無効	MANAGED または DEDICATED を使用する
AttachDynamicStorage	停止中のインスタンスは拒否される	インスタンスが RUNNING であることを確認する
AttachDynamicStorage	mount_path の形式	/data/ で始まり、/ で終わる必要がある
RegisterImage	arch の大文字・小文字が一致しない	大文字の X86_64／AARCH64 を使用する
RenewLease	type の大文字・小文字が一致しない	小文字の timing／idle を使用する

このステップは、すべての書き込み操作で必須です。省略すると、すでに文書化されている CLI パラメーターエラーや API の失敗が発生する可能性があります。

ステップ 3：書き込み操作に対応する

すべての書き込み操作（Create／Update／Delete／Start／Stop／Attach／Detach／Register／Sync／Renew）では、実行前にユーザーに確認を求めてください。課金対象の操作（CreateNotebook、StartNotebook）では、費用をユーザーに知らせるため、事前に BSS の料金を照会してください。料金照会のワークフローについては、references/pricing-inquiry.md を参照してください。

削除操作の対話ガイド：ユーザーがタグの削除（DeleteNotebookTags）、イメージグループの削除（DeleteImageGroup）などをリクエストしたものの、対象を具体的に指定していない場合は、まず現在の対象一覧（例：ShowNotebookTags／ListImageGroup）を照会し、削除する対象をユーザーに提示して確認してください。確認後に実行します。コンテキストが不明確なまま操作して、誤って削除することを防ぎます。

---

KooCLI コマンド形式の標準

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

機能	説明	例
サービス名	固定値：ModelArts	ModelArts
操作名	パスカルケース	ListNotebooks、CreateNotebook
リージョンパラメーター	--cli-region={region}	--cli-region=cn-north-4
単純なパラメーター	--key=value	--id=xxx
インデックス付きパラメーター	--key.1=value1	--tags.1.key=env
project_id	省略した場合は自動解決	設定済みのプロジェクト ID を使用

注：--project_id を省略すると、認証情報から自動的に解決されます。特定のプロジェクトを対象にする場合にのみ、明示的に指定してください。

---

主なコマンド

7 つの機能領域にわたる CLI コマンド例 31 件は、別のリファレンスファイルに記載されています。

📖 コマンド構文、パラメーター、例の詳細については、references/cli-command-examples.md をお読みください

クイックインデックス

#	ドメイン	API	主な操作
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

コマンドを実行する際は、正確なパラメーター名、必須／任意のフラグ、使用方法について、必ずリファレンスファイルを参照してください。

---

パラメーターの確認

パラメーター	必須	説明	例
{region}	はい	Huawei Cloud のリージョン	cn-north-4、cn-east-3
{instance_id}	はい（ほとんどの操作）	Notebook インスタンスの UUID	xxx-xxx-xxx
{image_id}	作成／一覧表示	イメージの UUID	xxx-xxx-xxx
{flavor_id}	作成	インスタンスのフレーバー ID	modelarts.bm.4xlarge.pro
{resource_id}	タグ操作	タグ付けするリソース ID	xxx-xxx-xxx
{cluster_id}	ShowCluster	クラスター ID	xxx-xxx-xxx
{storage_id}	ストレージ操作	ストレージ ID	xxx-xxx-xxx
{feature}	ListFeatures	機能名	NOTEBOOK
{project_id}	いいえ（自動）	プロジェクト ID。省略した場合は自動的に解決されます	デフォルトを使用する場合は省略

---

SDK へのフォールバック

CLI の不具合により CLI 操作が失敗した場合は、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()

---

リファレンスドキュメント

ドキュメント	説明
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	受け入れ基準のチェックリスト
references/api-paths.md	SDK ソースに記載された REST API パス
references/cli-installation-guide.md	CLI のインストールおよび認証ガイド
references/known-issues.md	既知の問題と回避策
references/pricing-inquiry.md	課金対象の操作に関する BSS 料金照会ガイド

既知の問題（概要）

詳細：references/known-issues.md

#	問題	要点
1	CLI の volume.category enum に EVS が含まれていない	body ラッパーを使用した --cli-jsonInput と、明示的な --project_id を使用してください
2	ストレージカテゴリと所有権の組み合わせ	EVS:MANAGED ✅、OBS/OBSFS:DEDICATED ✅、OBS/OBSFS:MANAGED ❌
3	DEDICATED の所有権には pool_id が必要	先に専用プールを照会し、トップレベルの pool_id を渡してください
4	OBS を data_volume として指定すると、エラーなしで失敗する	OBS をメインの volume として使用するか、OBSFS を data_volume として使用してください
5	バケットタイプ（POSIX または OBJECT）は無関係	どちらも DEDICATED の所有権で動作します
6	OBSFS:MANAGED の拡張ストレージは非対応	OBSFS には DEDICATED を使用してください
7	OBS/OBSFS のメインボリュームには dew_secret_name が必要	AK/SK を DEW/CSMS シークレットに保存してください
8	OBS データボリュームには mount_path が必要	常に有効なパスを指定してください
9	イメージとフレーバーのアーキテクチャが一致しない	イメージとフレーバーの arch フィールドを一致させてください
10	--cli-jsonInput の一般的な回避策	{"body":{...}} でラップし、--project_id を明示的に渡す必要があります
11	ShowLease の期間は残り時間ではなく合計時間	次の式で計算してください：remaining = (create_at + duration) - current_time
12	ListImageGroup の応答フィールドは --limit によって異なる	limit なしの場合は groups フィールド、limit ありの場合は data フィールドです。両方を解析してください
13	AttachDynamicStorage は POSIX バケットのみサポート	OBJECT バケットは ModelArts.6772 で拒否されます。obsutil stat で確認してください

---

注意事項

• 31 個すべての API インターフェースを hcloud ModelArts CLI から利用できます
• CLI で問題が発生した場合は、SDK v1 の huaweicloudsdkmodelarts にフォールバックできます
• リージョンは --cli-region で指定し、ハードコードしないでください
• --project_id を省略すると、認証情報から自動的に解決されます（ただし、--cli-jsonInput を使用する場合は明示的な指定が必須です）
• すべての書き込み操作（Create/Update/Delete/Start/Stop/Attach/Detach/Register/Sync/Renew）は、実行前にユーザーの確認が必要です
• 課金対象の操作（CreateNotebook、StartNotebook）では、実行前に BSS の料金照会を行い、ユーザーに費用を知らせる必要があります
• API パスは SDK ソースの _http_info にある resource_path から確認済みです。推測したエンドポイントはありません
• どのファイルにも AK/SK をハードコードしていません。認証情報は hcloud configure list/set を通じて管理します