huawei-cloud-swr-image-automation

Huawei Cloud SWR イメージ自動化

概要

このスキルは、hcloud CLI を使用した Huawei Cloud SWR（Software Repository for Container）のイメージ自動化機能を提供します。リージョン間のイメージ同期や、トリガーベースの自動デプロイに対応しています。

アーキテクチャ：hcloud CLI → SWR Service API → SyncRepo/Trigger/SyncJob/SyncRegion リソース

関連スキル：

• huawei-cloud-swr-image-management - イメージのライフサイクル管理（名前空間、リポジトリ、タグ、認証、クォータ）。トリガーをエンドツーエンドで検証するには、イメージのプッシュと認証（CreateAuthorizationToken、docker login、docker push）が必要です。 インストールされていない場合は、先にインストールしてください。

  npx skills add huaweicloud/huaweicloud-skills --skill huawei-cloud-swr-image-management -y
  

  イメージのプッシュと認証の一連の手順については、公式の SWR クイックスタートガイドを参照してください：https://support.huaweicloud.com/qs-swr/index.html

• huawei-cloud-swr-image-governance - イメージガバナンス（権限、保持、共有、タグ、不変ルール）

• huawei-cloud-swr-enterprise-instance - エンタープライズインスタンス管理

• プッシュ時にリージョン間でイメージを複製する自動同期を設定する

• 特定のイメージタグをターゲットリージョンに手動で同期する

• 利用可能な同期先リージョンを一覧表示する

• 同期ジョブの実行状況を確認する

• CCE/CCI ワークロードへの自動デプロイ用トリガーを作成、管理する

• トリガーを有効化／無効化し、設定を更新する

一般的なユースケース：

• 「イメージリポジトリから cn-east-3 への自動同期を設定する」
• 「イメージタグ v1.0 と v2.0 を別のリージョンに手動で同期する」
• 「イメージ同期に利用できるリージョンを一覧表示する」
• 「イメージ同期ジョブの状況を確認する」
• 「新しいイメージがプッシュされたときに CCE デプロイを自動更新するトリガーを作成する」
• 「リポジトリのすべてのトリガーを一覧表示する」
• 「トリガーを一時的に無効にする」
• 「古いトリガー設定を削除する」
• 「複数リージョン間でのイメージレプリケーションを設定する」

パラメーターの確認

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

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

1. 実行する正確な hcloud コマンドを表示する
2. 対象リソース（名前空間、リポジトリ、リモートリージョンなど）を示す
3. 適用する変更（同期設定、トリガー設定、上書き状態）を示す
4. 続行する前にユーザーの確認（「yes」／「confirm」）を待つ
5. ユーザーが拒否した場合は操作を中止し、手順 1 に戻る

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

操作	コマンド	リスクレベル	説明
自動同期設定の作成	CreateImageSyncRepo	🟠 高	リージョン間のイメージレプリケーションを作成します。override=true の場合、ターゲットリージョンにある既存のイメージを上書きします。既存のイメージは復元できません。続行する前にユーザーに警告してください
自動同期設定の削除	DeleteImageSyncRepo	🟡 中	自動同期設定を削除します。以降のプッシュはターゲットリージョンに自動複製されなくなります。すでに同期されたイメージは保持されます
タグの手動同期	CreateManualImageSyncRepo	🟡 中	特定のタグを一度だけ同期します。override=true の場合、ターゲットリージョンにある既存のイメージを上書きします
トリガーの作成	CreateTrigger	🟡 中	CCE/CCI への自動デプロイを設定します。新しいイメージがプッシュされると、ターゲットワークロードが自動的に更新されます。意図しないデプロイを避けるため、トリガー条件を確認してください
トリガーの更新	UpdateTrigger	🟡 中	トリガー設定を変更します。有効化／無効化すると、自動デプロイの動作が直ちに変わります
トリガーの削除	DeleteTrigger	🟡 中	自動デプロイトリガーを削除します。新しいイメージがプッシュされても、ターゲットワークロードは自動更新されなくなります

前提条件

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 を使用してください
  • ✅ クラウド操作には、ルートアカウントより IAM ユーザーを優先してください
  • ✅ 機密性の高い操作では MFA を有効にしてください

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

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

3. IAM 権限の要件

API アクション	権限	目的
swr:sync:create	同期リポジトリの作成	リージョン間のイメージ同期を設定する
swr:sync:delete	同期リポジトリの削除	同期設定を削除する
swr:sync:list	同期リポジトリの一覧表示	自動同期設定を照会する
swr:syncmanual:create	手動同期	手動でイメージ同期を実行する
swr:syncregion:list	同期リージョンの一覧表示	利用可能な同期先リージョンを照会する
swr:syncjob:get	同期ジョブのステータス取得	同期の実行ステータスを確認する
swr:trigger:create	トリガーの作成	自動デプロイトリガーを設定する
swr:trigger:list	トリガーの一覧表示	トリガー設定を照会する
swr:trigger:get	トリガーの取得	特定のトリガーの詳細を表示する
swr:trigger:update	トリガーの更新	トリガー設定を変更する
swr:trigger:delete	トリガーの削除	トリガー設定を削除する

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

権限エラーへの対応：

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

ワークフロー

0. ⚠️ 課金の確認（必須） — 操作を実行する前に、課金への影響の可能性をユーザーに伝え、明示的な同意を得てください。
   • リージョン間の同期：リージョン間でイメージを同期すると、リージョン間トラフィック料金が発生します。自動同期（syncAuto=true）ではイメージが継続的に複製されるため、継続的にトラフィック料金が発生します。
   • トリガーの実行：CCE／CCI にデプロイするトリガーでは、対象クラスターのコンピューティング料金が発生する場合があります。
   • ストレージ料金：同期されたイメージは、ソースリージョンとターゲットリージョンの両方でストレージを使用します。
   • ユーザーに次の内容を確認します。「課金への影響を理解したうえで、続行しますか？（はい／いいえ）」
   • ユーザーが明示的に同意した場合にのみ続行してください。同意しない場合は停止し、操作を実行しないでください。
1. パラメーターを確認する — 上記の確認表を見直し、書き込み操作の前にリスクレベルと主要なパラメーターをユーザーに確認します。
2. 同期先リージョンを照会する — ListSyncRegions を実行して、利用可能なリージョン間同期先を取得します。
3. 同期を設定する — 自動同期には CreateImageSyncRepo、1 回限りの手動同期には CreateManualImageSyncRepo を実行します。
4. トリガーを管理する — CreateTrigger／UpdateTrigger／DeleteTrigger を実行して、CCE／CCI への自動デプロイを設定します。
5. ステータスを照会する — ListImageAutoSyncReposDetails／ShowTrigger／ListSyncJobsDetails を実行して、同期とトリガーのステータスを確認します。
6. クリーンアップする — 同期を停止するには DeleteImageSyncRepo、トリガーを削除するには DeleteTrigger を実行します。

KooCLI コマンド形式の標準

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

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

主な規則：

• サービス名：SWR（大文字で、KooCLI のサービス一覧に一致します）
• 操作名：パスカルケース（例：CreateImageSyncRepo、ListSyncRegions、CreateTrigger）
• リージョンパラメーター：--cli-region=<value>（デフォルト：cn-north-4、または環境変数 HUAWEI_CLOUD_REGION）
• 出力形式：--cli-output=json（エージェントによる処理用）
• JMESPath フィルタリング：--cli-query="<expression>"（出力を減らすために使用します）
• 配列形式のパラメーター：--imageTag.1=v1 --imageTag.2=v2（インデックスは 0 ではなく 1 から始まります）

例 — 読み取り操作：

hcloud SWR ListSyncRegions --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 CreateImageSyncRepo --namespace=pancake --repository=openclaw-sandbox \
  --remoteRegionId=cn-east-3 --remoteNamespace=pancake --syncAuto=true --override=false \
  --cli-region=cn-north-4

主なコマンド

1. 自動同期（リージョン間のイメージ複製）

詳細なワークフローについては、タスク：イメージ同期を参照してください。

# List available sync target regions
hcloud SWR ListSyncRegions --cli-region=cn-north-4

# Configure auto-sync for a repository to target region
hcloud SWR CreateImageSyncRepo --namespace=group-dev --repository=my-app --remoteRegionId=cn-east-3 --remoteNamespace=group-dev --override=false --syncAuto=true --cli-region=cn-north-4

# List auto-sync configurations for a repository
hcloud SWR ListImageAutoSyncReposDetails --namespace=group-dev --repository=my-app --cli-region=cn-north-4

# Delete auto-sync configuration
hcloud SWR DeleteImageSyncRepo --namespace=group-dev --repository=my-app --remoteRegionId=cn-east-3 --remoteNamespace=group-dev --cli-region=cn-north-4

自動同期の動作：syncAuto=true の場合、ソースリポジトリに新しいイメージがプッシュされるたびに、ターゲットリージョンへの同期が自動的に開始されます。syncAuto=false の場合、同期は手動で開始した場合にのみ行われます。

⚠️ 照会の制限：ListImageAutoSyncReposDetails は syncAuto=true の設定のみを返します。syncAuto=false の設定は照会結果に表示されません。表示されない場合でも、作成に失敗したことを意味するわけではありません。

2. 手動同期

# Manually sync specific image tags to target region
hcloud SWR CreateManualImageSyncRepo --namespace=group-dev --repository=my-app --remoteRegionId=cn-east-3 --remoteNamespace=group-dev --imageTag.1=v1.0 --imageTag.2=v2.0 --override=false --cli-region=cn-north-4

⚠️ 重要：--imageTag には、通常の値形式ではなくインデックス付き配列形式を使用します。

• ✅ 正しい形式：--imageTag.1=v1.0 --imageTag.2=v2.0
• ❌ 誤った形式：--imageTag=v1.0（インデックスがありません）
• ❌ 誤った形式：--imageTag=v1.0,v2.0（カンマ区切りには対応していません）

3. 同期先リージョン

# List all regions available as sync targets
hcloud SWR ListSyncRegions --cli-region=cn-north-4

応答形式（実際の API で検証済み）：

[
  {
    "regionID": "cn-north-4"
  }

イメージを同期できるすべてのリージョンを返します。regionID フィールドの値を --remoteRegionId パラメーターとして使用します。

4. 同期ジョブのステータス

# Check sync job status (--filter is REQUIRED with limit and offset)
hcloud SWR ShowSyncJob --namespace=group-dev --repository=my-app --filter="limit::10|offset::0" --cli-region=cn-north-4

⚠️ 重要：--filter は必須であり、limit::N と offset::N の両方を含める必要があります（例："limit::10|offset::0"）。指定しない場合、コマンドは必須パラメーターが不足しているというエラーを返します。

応答形式（実際の API で検証済み）：フラットな JSON 配列を返します。同期ジョブがない場合は [] を返します。

5. トリガー管理（CCE/CCI への自動デプロイ）

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

# Create a trigger for auto-deploy to CCE
hcloud SWR CreateTrigger --namespace=group-dev --repository=my-app --name=deploy-trigger --trigger_type=all --condition=".*" --action=update --app_type=deployments --application=my-deployment --cluster_ns=default --enable=true --trigger_mode=cce --cluster_id=<cluster-id> --cluster_name=<cluster-name> --cli-region=cn-north-4

# List all triggers for a repository
hcloud SWR ListTriggersDetails --namespace=group-dev --repository=my-app --cli-region=cn-north-4

# Show trigger details
hcloud SWR ShowTrigger --namespace=group-dev --repository=my-app --trigger=deploy-trigger --cli-region=cn-north-4

# Update a trigger (enable/disable or modify configuration)
hcloud SWR UpdateTrigger --namespace=group-dev --repository=my-app --trigger=deploy-trigger --enable=false --cli-region=cn-north-4

# Delete a trigger
hcloud SWR DeleteTrigger --namespace=group-dev --repository=my-app --trigger=deploy-trigger --cli-region=cn-north-4

トリガーの種類：

• all：任意のイメージのプッシュ時にトリガーします（condition=".*"）
• tag：特定のタグのプッシュ時にトリガーします（condition=tag-name）
• regular：正規表現に一致するタグのプッシュ時にトリガーします（condition=regex-pattern）

トリガーモード：

• cce：CCE（Cloud Container Engine）クラスターにデプロイします — --cluster_id が必要です
• cci：CCI（Cloud Container Instance）にデプロイします — クラスター ID は不要です

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

共通パラメーター

パラメーター	必須／任意	説明	デフォルト
--cli-region	必須	Huawei Cloud のリージョン ID	設定値または HUAWEI_CLOUD_REGION
--namespace	コンテキストに依存	SWR の名前空間（組織）	該当なし
--repository	コンテキストに依存	イメージリポジトリ名	該当なし

自動同期パラメーター

パラメーター	必須	説明	制約
--namespace	はい	ソースの名前空間	既存の名前空間名
--repository	はい	ソースリポジトリ	既存のリポジトリ名
--remoteRegionId	はい	ターゲットのリージョン ID	ListSyncRegions の結果に含まれている必要があります
--remoteNamespace	はい	ターゲットの名前空間	ターゲットリージョン内の名前空間名
--override	いいえ	既存のイメージを上書きします	true または false（デフォルトは false）
--syncAuto	いいえ	プッシュ時に自動同期します	true または false（デフォルトは false）

手動同期パラメーター

パラメーター	必須	説明	制約
--namespace	はい	ソースの名前空間	既存の名前空間名
--repository	はい	ソースリポジトリ	既存のリポジトリ名
--remoteRegionId	はい	ターゲットのリージョン ID	ListSyncRegions の結果に含まれている必要があります
--remoteNamespace	はい	ターゲットの名前空間	ターゲットリージョン内の名前空間名
--imageTag.[N]	はい	タグのリスト（インデックス付き配列）	--imageTag.1=v1.0 --imageTag.2=v2.0
--override	いいえ	既存のイメージを上書きします	true または false（デフォルトは false）

トリガーパラメーター

パラメーター	必須	説明	制約
--namespace	はい	SWR の名前空間	既存の名前空間名
--repository	はい	イメージリポジトリ	既存のリポジトリ名
--name	はい	トリガー名	リポジトリ内で一意であること
--trigger_type	はい	トリガータイプ	all、tag、regular
--condition	はい	一致条件	すべての場合は .*、タグの場合はタグ名、正規表現の場合は正規表現
--action	はい	トリガーアクション	update
--app_type	はい	アプリケーションタイプ	deployments または statefulsets
--application	はい	CCE/CCI アプリケーション名	既存のデプロイメント名
--cluster_ns	はい	アプリケーションの名前空間	Kubernetes の名前空間（例：default）
--enable	はい	トリガーを有効化	true または false
--trigger_mode	いいえ	デプロイ先	cce（デフォルト）または cci
--cluster_id	CCE のみ	CCE クラスター ID	cce モードでは必須、cci では空欄
--cluster_name	いいえ	CCE クラスター名	クラスター名は任意
--container	いいえ	対象コンテナ	特定のコンテナ名（デフォルト：すべて）

出力形式

ListSyncRegions（検証済み）

レスポンスはリージョンオブジェクトのフラットな JSON 配列です。

[
  {
    "regionID": "cn-north-4",
    "region_name": "north-1"
  }
]

注：利用可能な同期先リージョンをすべて返します。region_id を --remoteRegionId として使用してください。

ListImageAutoSyncReposDetails

レスポンス形式は未検証です。同期リポジトリの設定が存在する場合は一覧を返し、自動同期が設定されていない場合は空を返します。

⚠️ 制限：syncAuto=true（自動同期）の設定のみを返します。syncAuto=false（手動同期のみ）の設定は結果に表示されません。回避策については、タスク：イメージ同期 の W3 を参照してください。

ListTriggersDetails

レスポンス形式は未検証です。トリガーオブジェクトが存在する場合は一覧を返し、トリガーが設定されていない場合は空を返します。

ShowTrigger

レスポンス形式は未検証です。パラメーターとして --namespace、--repository、--trigger（トリガー名）を使用してください。

ShowSyncJob（検証済み）

レスポンスはフラットな JSON 配列です。同期ジョブが存在しない場合は [] を返します。

[]

注：--filter="limit::N|offset::N" パラメーターが必要です。使用方法については、同期ジョブのステータスを参照してください。

検証

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

よく使われるリージョン ID

リージョン名	リージョン ID
中国北部 - 北京 4	cn-north-4
中国北部 - 北京 1	cn-north-1
中国東部 - 上海 1	cn-east-3
中国東部 - 上海 2	cn-east-2
中国南部 - 広州	cn-south-1
中国南部 - 深圳	cn-south-4
中国西南部 - 貴陽 1	cn-southwest-2
アジア太平洋 - バンコク	ap-southeast-2
アジア太平洋 - シンガポール	ap-southeast-1
アジア太平洋 - 香港	ap-southeast-3
ヨーロッパ - パリ	eu-west-0

ベストプラクティス

1. 本番リポジトリでは自動同期：イメージがターゲットリージョンに自動的に複製されるよう、本番リポジトリでは syncAuto=true を設定します
2. 選択的な複製には手動同期：特定のタグ（本番リリースなど）のみを同期する場合は、CreateManualImageSyncRepo を使用します
3. 上書きには注意：ターゲットリージョンの既存イメージを意図的に上書きする場合に限り、override=true を設定します
4. トリガーの命名：内容が分かるトリガー名（例：prod-deploy-trigger、staging-update-trigger）を使用します
5. トリガー条件の設計：柔軟なマッチングには、正規表現と trigger_type=regular を使用します（例：semver タグには v\d+\.\d+\.\d+）
6. 削除前に無効化：クリーンアップ中の意図しないデプロイを避けるため、トリガーを削除する前に無効化（enable=false）します
7. ターゲット名前空間の確認：同期設定を作成する前に、ターゲットリージョンにターゲット名前空間が存在することを確認します
8. リージョン間で名前空間を統一：リージョン間の管理を簡単にするため、リージョン間で同じ名前空間名を使用します
9. まず同期リージョンを確認：ターゲットリージョンが利用可能であることを確認するため、同期設定を作成する前に必ず ListSyncRegions を実行します

参考資料

ドキュメント	説明
SWR Automation API ガイド	hcloud SWR 自動化 API リファレンス
IAM 権限ポリシー	必要な権限とポリシー JSON
検証方法	段階的な検証手順
よくある落とし穴	トラブルシューティングガイド
タスク：イメージ同期	自動／手動同期のワークフロー
タスク：トリガー管理	トリガーのワークフロー
CLI インストールガイド	KooCLI のセットアップと認証情報の設定
受け入れ基準	正常／エラーパターンの比較

注意事項

• 自動同期は継続的に有効です — 一度設定すると、削除されるまで新しいプッシュのたびに自動的に実行されます
• 手動同期は一度限りです — CreateManualImageSyncRepo を実行するたびに、指定したタグが一度同期されます
• --imageTag.[N] はインデックス付き配列形式を使用します — 単一の値やカンマ区切りではありません
• 同期先の名前空間が存在している必要があります — 同期前に、ターゲットリージョンに名前空間を作成します
• AK/SK をハードコードしてはいけません — 認証情報は環境変数からのみ取得してください
• サポート対象の方法は hcloud CLI のみです — すべての操作で hcloud SWR <Operation> 形式を使用します
• トリガーには CCE/CCI クラスターが必要です — トリガーは、既存の CCE クラスターまたは CCI インスタンスでのみ動作します
• レスポンス形式は検証待ちです — ListImageAutoSyncReposDetails、ListTriggersDetails、ShowTrigger のレスポンス形式は、実環境での検証が必要です
• CLI の終了コードには制限があります — hcloud CLI（KooCLI 7.2.2）は、SWR API がエラーを返しても終了コード 0 を返す場合があります。自動化スクリプトでは、終了コードだけに依存してはいけません。成功／失敗を判定するには、出力に error_code または error_msg フィールドが含まれているか確認してください
• 事前検証が必要です — SWR API は、リクエスト時にターゲット名前空間の存在、タグの存在、リージョンの有効性を検証しません。同期設定や手動同期ジョブを作成する前に、必ず事前検証（ShowNamespace、ListRepositoryTags、ListSyncRegions）を実行してください
• CCI の認可が前提条件です — trigger_mode=cci トリガーを作成する前に、hcloud CCI ListNamespaces を実行して CCI サービスが認可されていることを確認してください。CCI が認可されていない場合、認可に関するヒントではなく、誤解を招く「Server internal error」が返されます

よくある落とし穴

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

クイックリファレンス：

落とし穴	症状	すぐにできる対処法
--imageTag の形式が間違っている	手動同期に失敗する	インデックス付きで指定します：--imageTag.1=v1.0
同期先のネームスペースが存在しない	同期の作成に失敗する	先に同期先リージョンにネームスペースを作成します
remoteRegionId が無効	同期の作成に失敗する	ListSyncRegions で確認します
CCE クラスターが見つからない	トリガーの作成に失敗する	CCE コンソールで cluster_id を確認します
トリガーがすでに存在する	409 Conflict	先に ShowTrigger で確認します
CCI が認可されていない	"Server internal error"	先にコンソールで CCI を認可します
CreateTrigger で "Invalid param"	一般的なエラーで、複数の原因が考えられます	名前／クラスター／アプリの存在を事前に確認します
API エラーでも終了コードが 0	スクリプトが成功と判断する	終了コードではなく、出力の error_code を確認します
syncAuto=false が一覧にない	設定が欠落しているように見える	ListImageAutoSyncReposDetails は true の場合のみ表示します
存在しないネームスペースへの同期	何も表示されず成功し、設定が無効になる	先に ShowNamespace でネームスペースを確認します
意図しない自動同期	イメージが予期せず同期される	syncAuto=false を設定するか、同期設定を削除します