huawei-cloud-swr-image-management

Huawei Cloud SWR イメージ管理

概要

このスキルでは、hcloud CLI を使用して Huawei Cloud SWR（Software Repository for Container）イメージのライフサイクルを管理できます。

アーキテクチャ：hcloud CLI → SWR Service API → Namespace/Repository/Tag/Auth/Quota リソース

• SWR の名前空間（組織）を作成・管理します
• 公開／非公開の設定でイメージリポジトリを作成・管理します
• イメージのタグ／バージョンを照会・管理します
• Docker のログイン認証情報（一時的および長期的）を取得します
• SWR リソースのクォータを確認します

一般的なユースケース：

• 「プロジェクト用の SWR 名前空間を作成する」
• 「名前空間 'group-dev' 内のすべてのイメージリポジトリを一覧表示する」
• 「名前空間 'group-dev' のリポジトリ 'nginx' のイメージタグを照会する」
• 「SWR の Docker ログインコマンドを取得する」
• 「古いイメージタグを削除してストレージを整理する」
• 「SWR のクォータ使用状況を確認する」
• 「カスタムイメージ用の非公開リポジトリを作成する」
• 「リポジトリの説明と公開範囲を更新する」

ワークフロー

0. ⚠️ 料金の確認（必須） — いずれかの操作を実行する前に、料金が発生する可能性をユーザーに伝え、明示的な同意を得ます。
   • SWR 基本サービス：SWR 基本サービスはクォータ内であれば無料です。名前空間またはリポジトリのクォータを超えると、料金が発生するエンタープライズインスタンスへのアップグレードが必要になる場合があります。
   • ストレージ料金：SWR 内のイメージストレージは OBS ストレージを消費します。イメージが大きい場合やタグの数が多い場合は、ストレージ料金が増加します。
   • 通信料金：イメージのプル／プッシュを頻繁に行うと、特にリージョンをまたぐ場合に、ネットワーク通信料金が発生することがあります。
   • ユーザーに次のように確認します：「料金への影響を理解したうえで、続行しますか？（yes/no）」
   • ユーザーが明示的に同意した場合のみ続行します。ユーザーが拒否した場合は停止し、操作を実行しません。
1. ユーザーのリクエストを解析 — SWR の操作（名前空間、リポジトリ、タグ、認証、クォータ）を特定します
2. 前提条件を確認 — hcloud CLI のインストールと認証情報の設定を確認します
3. パラメーターを確認 — 操作、対象リソース、パラメーターをユーザーに表示して確認します
4. 読み取り操作を実行 — 照会操作（Show、List）では、hcloud CLI を直接実行します
5. 書き込み操作を確認 — 書き込み操作（Create、Update、Delete）では、実行前にユーザーへ確認を求めます（パラメーターの確認を参照）
6. 出力を解析して整形 — 関連するフィールドを抽出し、表または構造化された形式で整形します
7. 結果を報告 — コンテキスト（例：名前空間が作成された、リポジトリの公開範囲が変更された）とともに結果を提示します
8. 次のアクションを提案 — 関連する操作を提案します（例：名前空間の作成後に、リポジトリの作成を提案します）

パラメーターの確認

すべての書き込み操作（作成、更新、削除）を実行する前に、ユーザーの明示的な確認が必要です。

書き込み操作を実行する前に、スキルは次のことを行う必要があります。

1. 実行する正確な hcloud コマンドを表示する
2. 対象のリソース（ネームスペース、リポジトリ、タグなど）を表示する
3. 適用する変更（作成、削除、公開設定の変更）を表示する
4. 先に進む前に、ユーザーの確認（「yes」／「确认」）を待つ
5. ユーザーが拒否した場合、操作を中止し、手順 1 に戻る

確認が必要な書き込み操作：

操作	コマンド	リスクレベル	説明
ネームスペースの作成	CreateNamespace	中	新しい SWR ネームスペースを作成します（クォータを消費します）
リポジトリの作成	CreateRepo	中	新しいイメージリポジトリを作成します
リポジトリの更新	UpdateRepo	中	リポジトリの公開設定（公開／非公開）を変更します。is_public を true に変更する場合（非公開→公開）、明示的なセキュリティ警告を表示する必要があります。⚠️ 公開リポジトリでは、すべてのユーザーがイメージをプルできるため、セキュリティリスクが生じる可能性があります。スキルはユーザーに警告し、先に進む前に明示的な確認を求める必要があります。ユーザーが拒否した場合、操作を中止します。
ネームスペースの削除	DeleteNamespaces	高	ネームスペースと、その配下のすべてのリポジトリ／イメージを削除します
リポジトリの削除	DeleteRepo	高	リポジトリと、すべてのイメージタグを完全に削除します
タグの削除	DeleteRepoTag	高	イメージタグを完全に削除します（取り消し不可）

前提条件

1. hcloud CLI の要件（必須）

• hcloud CLI がインストールされていること（バージョン >= 7.2.2）
• hcloud version を実行して、インストールを確認します
• 初回利用時：プライバシーに関する声明に同意するには、printf "y\n" | hcloud version を実行します

2. 認証情報の設定

hcloud CLI は、環境変数を使った 2 種類の認証情報モードをサポートしており、実行時に自動的に判別します。

モード A — 長期 AK/SK（永続的なアクセス）：

export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>
export HUAWEI_CLOUD_REGION=cn-north-4

モード B — 一時的な AK/SK + SecurityToken（一時的なアクセスや委任されたアクセスに推奨）：

export HUAWEI_CLOUD_AK=<your-temp-ak>
export HUAWEI_CLOUD_SK=<your-temp-sk>
export HUAWEI_CLOUD_SECURITY_TOKEN=<your-security-token>
export HUAWEI_CLOUD_REGION=cn-north-4

HUAWEI_CLOUD_SECURITY_TOKEN が設定されている場合、hcloud CLI は一時認証情報による認証を自動的に使用します。AK/SK のみが設定されている場合は、長期認証情報による認証を使用します。

• セキュリティルール：
  • 🚫 AK/SK/SecurityToken の値を、コード、会話、コマンドで決して公開しないでください
  • 🚫 認証情報の確認に echo $HUAWEI_CLOUD_AK や echo $HUAWEI_CLOUD_SK を決して使用しないでください
  • ✅ 環境変数を使用します：HUAWEI_CLOUD_AK、HUAWEI_CLOUD_SK、HUAWEI_CLOUD_REGION、HUAWEI_CLOUD_SECURITY_TOKEN
  • ✅ クラウド操作には、root アカウントより IAM ユーザーを優先して使用してください
  • ✅ 機密性の高い操作には MFA を有効にしてください

⚠️ 重要なセキュリティ上の注意事項：

• 認証情報をバージョン管理に決してコミットしないでください
• 必要最小限の権限を持つ IAM ユーザーを使用してください
• 機密性の高い操作には MFA を有効にしてください
• AK/SK を定期的にローテーションしてください

3. IAM 権限の要件

API アクション	権限	目的
swr:namespace:create	名前空間の作成	SWR 組織を作成する
swr:namespace:list	名前空間の一覧表示	すべての名前空間を照会する
swr:namespace:get	名前空間の取得	個々の名前空間の情報を表示する
swr:namespace:delete	名前空間の削除	組織を削除する
swr:repository:create	リポジトリの作成	イメージリポジトリを作成する
swr:repository:list	リポジトリの一覧表示	イメージリポジトリを照会する
swr:repository:get	リポジトリの取得	リポジトリの詳細を表示する
swr:repository:update	リポジトリの更新	リポジトリのプロパティを変更する
swr:repository:delete	リポジトリの削除	イメージリポジトリを削除する
swr:tag:list	タグの一覧表示	イメージタグ／バージョンを照会する
swr:tag:get	タグの取得	特定のタグの詳細を表示する
swr:tag:create	タグの作成	イメージタグを作成する
swr:tag:delete	タグの削除	イメージタグを削除する
swr:login:get	ログイントークンの取得	Docker ログイン認証情報を取得する
swr:quota:get	クォータの取得	リソースのクォータを確認する

ポリシー JSON の全容については、IAM 権限ポリシーを参照してください。

権限エラーへの対応：

1. 権限エラーが原因でコマンドが失敗した場合は、references/iam-policies.mdを読み込みます
2. 必要な権限の一覧とポリシー JSON をユーザーに表示します
3. IAM コンソールでカスタムポリシーを作成し、権限を付与するようユーザーに案内します
4. 実行を一時停止し、権限が付与されたことをユーザーが確認するまで待ちます

KooCLI コマンド形式の標準

すべてのコマンドは、標準の hcloud KooCLI 形式に従います。

hcloud SWR <Operation> --param1=value1 --param2=value2 --cli-region=<region>

主な規則：

• サービス名：SWR（大文字表記。KooCLI のサービス一覧と一致します）
• オペレーション名：パスカルケース（例：ShowNamespace、CreateRepo、ListRepoTags）
• リージョンパラメーター：--cli-region=<value>（デフォルト：cn-north-4、または HUAWEI_CLOUD_REGION 環境変数）
• 出力形式：--cli-output=json（エージェントでの処理用）
• JMESPath フィルタリング：--cli-query="<expression>"（出力を絞り込むため）
• オブジェクト型パラメーター：JSON 文字列形式 --key={subkey:value}

例 — 読み取り操作：

hcloud SWR ShowNamespace --namespace=pancake --cli-region=cn-north-4 --cli-output=json

例 — 書き込み操作（ユーザーの確認が必要）：

# Step 1: Display command and parameters for user confirmation
# Step 2: After user confirms, execute:
hcloud SWR CreateNamespace --namespace=my-project --cli-region=cn-north-4

コアコマンド

1. 名前空間（組織）の管理

詳細なワークフローについては、タスク：名前空間の管理を参照してください。

# List all namespaces
hcloud SWR ListNamespaces --cli-region=cn-north-4

# List namespaces with filter
hcloud SWR ListNamespaces --filter="namespace::group-dev|mode::visible" --cli-region=cn-north-4

# Show namespace details
hcloud SWR ShowNamespace --namespace=group-dev --cli-region=cn-north-4

# Create a namespace
hcloud SWR CreateNamespace --namespace=group-dev --cli-region=cn-north-4

# Delete a namespace (CAUTION: removes all repos under it)
hcloud SWR DeleteNamespaces --namespace=group-dev --cli-region=cn-north-4

名前空間の命名規則：

• 小文字で始めます
• 以降は小文字、数字、ピリオド、アンダースコア、ハイフンを使用できます
• アンダースコアの連続は最大 2 個です
• ピリオド、アンダースコア、ハイフンを直接つなげることはできません
• 小文字または数字で終わる必要があります
• 長さ：1～64 文字

2. リポジトリ（イメージリポジトリ）の管理

詳細なワークフローについては、タスク：リポジトリの管理を参照してください。

# List all repositories
hcloud SWR ListReposDetails --cli-region=cn-north-4

# List repositories in a namespace
hcloud SWR ListReposDetails --namespace=group-dev --cli-region=cn-north-4

# List repositories with pagination and sorting
hcloud SWR ListReposDetails --namespace=group-dev --limit=20 --offset=0 --order_column=updated_time --order_type=desc --cli-region=cn-north-4

# List repositories by category
hcloud SWR ListReposDetails --category=database --cli-region=cn-north-4

# Show repository details
hcloud SWR ShowRepository --namespace=group-dev --repository=nginx --cli-region=cn-north-4

# Create a repository
hcloud SWR CreateRepo --namespace=group-dev --repository=my-app --is_public=false --category=other --description="Custom app image" --cli-region=cn-north-4

# Update repository (change visibility, description, category)
# ⚠️ SECURITY WARNING: When changing is_public to true (private→public):
#   "Public repositories allow any user to pull images, which may pose security risks."
#   The skill MUST display this warning and require explicit user confirmation before proceeding.
hcloud SWR UpdateRepo --namespace=group-dev --repository=my-app --is_public=true --description="Updated description" --cli-region=cn-north-4

# Delete a repository (CAUTION: removes all image tags)
hcloud SWR DeleteRepo --namespace=group-dev --repository=my-app --cli-region=cn-north-4

リポジトリの命名規則：

• 小文字または数字で始めます
• 以降は小文字、数字、ピリオド、スラッシュ、アンダースコア、ハイフンを使用できます
• アンダースコアの連続は最大 2 個です
• ピリオド、スラッシュ、アンダースコア、ハイフンを直接つなげることはできません
• 小文字または数字で終わる必要があります
• 長さ：1～128 文字

リポジトリのカテゴリ：app_server、linux、framework_app、database、lang、other、windows、arm

3. イメージタグ（バージョン）の管理

詳細なワークフローについては、タスク：タグの管理を参照してください。

# List all tags in a repository
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --cli-region=cn-north-4

# List tags with pagination and sorting
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --limit=50 --offset=0 --order_column=updated_at --order_type=desc --cli-region=cn-north-4

# Search for a specific tag
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --filter="tag::v1.0" --cli-region=cn-north-4

# Show tag details (image digest, size, create time)
hcloud SWR ShowRepoTag --namespace=group-dev --repository=nginx --tag=v1.0 --cli-region=cn-north-4

# Create a tag (retag existing image)
hcloud SWR CreateRepoTag --namespace=group-dev --repository=nginx --source_tag=v1.0 --destination_tag=v1.0-stable --override=false --cli-region=cn-north-4

# Delete a tag (CAUTION: removes the image version permanently)
hcloud SWR DeleteRepoTag --namespace=group-dev --repository=nginx --tag=v1.0-old --cli-region=cn-north-4

4. Docker ログインと認証

詳細なワークフローについては、タスク：認証管理を参照してください。

# Get temporary docker login credentials (valid for 12 hours)
hcloud SWR CreateAuthorizationToken --cli-region=cn-north-4

# Get long-term docker login credentials (valid for 1 year)
hcloud SWR CreateSecret --cli-region=cn-north-4

レスポンス形式（実際の API で検証済み）：

レスポンスは Docker 認証設定オブジェクトを返します。

{
  "auths": {
    "swr.cn-north-4.myhuaweicloud.com": {
      "auth": "base64-encoded-auth-token"
    }
  }
}

• auths：Docker 設定の認証オブジェクト。レジストリホストがキーです
• auth：Base64 でエンコードされた username:password 文字列

Docker ログイン：

⚠️ セキュリティ：エージェントは auth フィールドをデコードしてはいけません。以下のコマンドをユーザーに提示し、ユーザー自身のターミナルで実行してもらってください。

エージェントは API レスポンスから auth フィールドの値を取り出し、以下のコマンドをユーザーに提示してください。

# User runs these in their terminal (agent must NOT execute):
echo <auth_value> | base64 -d  # Outputs username:password
docker login -u <username> -p <password> swr.cn-north-4.myhuaweicloud.com

5. クォータ管理

詳細なワークフローについては、タスク：クォータ管理を参照してください。

# Check SWR quotas
hcloud SWR ListQuotas --cli-region=cn-north-4

パラメーターリファレンス

各コマンドの詳細なパラメーターテーブルと有効な値については、パラメーターリファレンスを参照してください。

出力形式

すべての SWR API コマンドの JSON レスポンス形式については、出力形式リファレンスを参照してください。

検証

手順に沿った検証については、検証方法を参照してください。

ベストプラクティス

1. ネームスペースの整理：チーム／プロジェクトの命名規則に従い、内容が分かりやすいネームスペース名を使用します（例：team-backend、proj-ai）
2. リポジトリの公開設定：内部イメージには is_public=false を設定し、一般公開を目的としたイメージにのみ is_public=true を設定します
3. タグの命名規則：セマンティックバージョニング（例：v1.0、v1.0-stable、latest）を使用し、曖昧なタグは避けます
4. 定期的なクリーンアップ：ストレージクォータを管理するため、古くなったタグを定期的に削除します
5. 再プッシュではなくタグ付け：同じイメージを複数回プッシュする代わりに、CreateRepoTag を使用してバージョンのエイリアスを作成します
6. CI/CD の長期ログイン：自動化パイプラインには CreateSecret を使用し、一時的なアクセスには CreateAuthorizationToken を使用します
7. 削除は慎重に：ネームスペースを削除すると、その配下のすべてのリポジトリが削除されます。リポジトリを削除すると、すべてのタグが削除されます

関連機能（エージェントによるオーケストレーション）

以下の機能はこのスキルでは提供されません。エージェントは別のスキルを通じてこれらをオーケストレーションできます。

スキル	説明
huawei-cloud-swr-enterprise-instance	エンタープライズ SWR インスタンス管理：インスタンスの作成／削除、アクセスエンドポイントの設定、長期認証情報の管理、イメージのセキュリティスキャン（StartManualScanning）、ビルド履歴（ShowInstanceArtifactAddition --addition=build_history）、イメージ同期レジストリ
huawei-cloud-swr-image-automation	SWR イメージ自動化：リージョン間のイメージ自動同期、CCE/CCI へのトリガーベースのデプロイ
huawei-cloud-swr-image-governance	SWR イメージガバナンス：保持ポリシー、共有ダウンロードドメイン、ネームスペース／リポジトリの認可

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

ドキュメント	説明
SWR API ガイド	hcloud SWR API リファレンス
パラメーターリファレンス	パラメーターテーブルとリージョン ID
出力形式	JSON レスポンス形式
IAM 権限ポリシー	必要な権限とポリシー JSON
検証方法	検証手順
よくある落とし穴	トラブルシューティングガイド
タスク：名前空間の管理	名前空間のワークフロー
タスク：リポジトリの管理	リポジトリのワークフロー
タスク：タグの管理	タグのワークフロー
タスク：認証情報の管理	ログイン認証情報のワークフロー
タスク：クォータの管理	クォータ確認のワークフロー
CLI インストールガイド	hcloud のインストール、設定、検証
受け入れ基準	正常／エラーパターンの比較

サポート対象外の操作

このスキルでは、hcloud CLI を使って SWR の名前空間、リポジトリ、タグ、認証情報、クォータを管理します。以下の操作は、このスキルではサポートされていません。

イメージのプッシュ／プル（docker CLI 操作）

このスキルでは、CreateAuthorizationToken または CreateSecret を通じて docker ログイン認証情報を提供しますが、docker push や docker pull は実行しません。認証情報を取得した後は、docker CLI を直接使用してください。

手順：

1. 認証情報を取得する — このスキルを使って SWR のログイン認証情報を取得します
2. 認証トークンをユーザーに提示する — レスポンスから auth フィールドを抽出し、ユーザーに提示します。⚠️ エージェントはこのフィールドをデコードしてはいけません。
3. ユーザーがデコードしてログインする — ユーザーはターミナルで次のコマンドを実行します。

# User runs these in their terminal (agent must NOT execute):
echo <auth_value> | base64 -d  # Outputs username:password
docker login -u <username> -p <password> swr.cn-north-4.myhuaweicloud.com

4. イメージをプッシュ／プルする — ユーザーは標準の docker CLI コマンドを使用します。

docker push swr.cn-north-4.myhuaweicloud.com/<namespace>/<repo>:<tag>
docker pull swr.cn-north-4.myhuaweicloud.com/<namespace>/<repo>:<tag>

長期利用の CI/CD 認証情報には、CreateAuthorizationToken ではなく CreateSecret を使用してください（有効期間は 12 時間ではなく 1 年です）。

イメージのセキュリティスキャン

イメージのセキュリティスキャンは、このスキルでは提供されていません。エンタープライズ SWR インスタンスが必要であり、Huawei Cloud HSS（Host Security Service）に依存します。StartManualScanning API はエンタープライズ SWR インスタンスでのみ利用可能で、基本 SWR では利用できません。

エンタープライズインスタンスでスキャンが有効かどうかを確認するには、インスタンスの設定を照会し、enableArtifactScanning フィールドを確認してください（SWR API ドキュメントを参照）。enableArtifactScanning が false の場合は、まずエンタープライズインスタンスでスキャンを有効にする必要があります。

イメージのセキュリティスキャンは、このスキルではサポートされていません。ユーザーは HSS（Host Security Service）を有効にし、SWR の Web コンソールからスキャンを実行してください。

ビルド履歴

ビルド履歴は基本 SWR では利用できません。エンタープライズ SWR インスタンスでは、--addition=build_history を指定して ShowInstanceArtifactAddition API からビルド履歴を照会できます（SWR API ドキュメントを参照）。

# Query build history for an enterprise instance artifact (requires instance_id)
hcloud SWR ShowInstanceArtifactAddition --instance_id={instance_id} --namespace_name={ns} --repository_name={repo} --reference={digest} --addition=build_history --cli-region=cn-north-4

基本 SWR（エンタープライズ以外）では、イメージのビルド機能は SWR Web コンソール（https://console.huawei.com/swr）でのみ利用できます。

外部イメージのインポート

SWR API には、イメージを直接インポートする操作がありません。Docker Hub などから外部イメージをインポートするには、docker CLI の再タグ付けとプッシュのワークフローを使用します。

# Step 1: Pull the external image
docker pull docker.io/library/nginx:latest

# Step 2: Get SWR login credentials from this skill
hcloud SWR CreateAuthorizationToken --cli-region=cn-north-4

# Step 3: Tag and push to SWR
docker tag docker.io/library/nginx:latest swr.cn-north-4.myhuaweicloud.com/<namespace>/nginx:latest
docker push swr.cn-north-4.myhuaweicloud.com/<namespace>/nginx:latest

制限事項：

• このワークフローを使用するには、docker CLI がローカルにインストールされ、実行されている必要があります（Docker Desktop や dockerd など）。
• ネットワーク帯域幅によっては、大容量のイメージのプルとプッシュにかなりの時間がかかる場合があります。
• プルしたイメージを一時的に保存できる十分なディスク容量が、ローカルマシンに必要です。

書き込み操作の戻り値

書き込み操作の戻り値と書き込み後の検証手順については、検証方法を参照してください。

ページネーションパラメーターの適用範囲

ページネーションパラメーターの適用範囲の詳細については、SWR API ガイドを参照してください。

注意事項

• ネームスペースの削除は取り消せません — 配下のすべてのリポジトリとイメージが削除されます
• リポジトリの削除は取り消せません — すべてのイメージタグが完全に削除されます
• タグの削除は取り消せません — イメージのバージョンを復元できません
• AK/SK をハードコードしてはいけません — 認証情報は環境変数からのみ取得してください
• サポートされている方法は hcloud CLI のみです — すべての操作で hcloud SWR <Operation> の形式を使用します
• 大規模なデータセットではページネーションが必要です — リポジトリとタグの一覧表示には --limit と --offset を使用してください

よくある落とし穴

詳しいトラブルシューティングガイドについては、よくある落とし穴と解決策を参照してください。

クイックリファレンス：

落とし穴	症状	すぐにできる対処法
無効なネームスペース名	400 Bad Request	命名規則に従ってください：小文字、1〜64 文字
ネームスペースが見つからない	404 Not Found	ShowNamespace でネームスペースの存在を確認してください
リポジトリがすでに存在する	409 Conflict	まず ShowRepository で確認してください
タグのダイジェストが一致しない	再タグ付けに失敗する	ShowRepoTag で source_tag の存在を確認してください
クォータ超過	403 Quota limit	ListQuotas でクォータを確認してください
認証トークンの期限切れ	Docker ログインに失敗する	CreateAuthorizationToken で再生成してください
Tag フィールド名	タグのクエリが予期しない構造を返す	name ではなく Tag（大文字の T）を使用してください
num_images は tag_count ではない	リポジトリ一覧のフィールドが一致しない	レスポンスでは num_images が使用され、--order_column では tag_count が使用されます