use-sealos

Sealos の使用

Sealos のリソースモデル

Sealos Cloud はマルチテナント Kubernetes プラットフォームです。ユーザーが所有するものはすべて、ワークスペースごとに 1 つの namespace（ns-xxx）にあり、制限付きの kubeconfig（~/.sealos/kubeconfig）を使ってアクセスします。namespace 内では、次のようになっています。

• アプリは、通常の Deployment／StatefulSet ＋ Service ＋ Ingress で、cloud.sealos.io/app-deploy-manager: <app> というラベルが付いています。これにより、Sealos の「App Launchpad」UI から管理できます。<host>.<region-domain> 経由のパブリック HTTPS とワイルドカード証明書は無料で利用できます。
• データベースは、KubeBlocks の Cluster CR で、「Database」UI から管理されます。
• テンプレートストアには、200 以上のワンクリックテンプレート（sealos-api.py store-list）があります。デプロイしたテンプレートはインスタンスとして記録され、UI に表示されます。
• オブジェクトストレージのバケットは ObjectStorageBucket CR であり、S3 互換の認証情報は管理対象のシークレットに格納されます。
• リージョンは、1 つのクラスターとドメインの組み合わせです（例：海外向けの usw-1.sealos.io、中国向けの bja.sealos.run など）。Template API は https://template.<region-domain> にあります。

ツール

scripts/ と references/ は、プロジェクトの作業ディレクトリではなく、このスキルのディレクトリを基準に解決してください。

• scripts/sealos-api.py — 認証（status、login、workspaces、switch）と Template API（deploy、store-list）を扱います。生の kubectl apply ではなく Template API 経由でデプロイすると、Sealos UI に削除可能な単位としてリソースが表示されます。
• export KUBECONFIG=~/.sealos/kubeconfig を設定した kubectl — 読み取り、デバッグ、削除に使用します。kubeconfig は namespace のスコープに限定されているため、他のテナントを確認したり操作したりすることはできません。
• scripts/wait-app.sh — デプロイ後の検証（ワークロードの準備状況＋URL のプローブ＋失敗時の診断）を行います。
• docker buildx — ソースビルドの経路でのみ使用します。

事前確認

SEALAI_DEPLOY_MODE が managed（Brain が管理するサンドボックス）に設定されている場合は、ここで作業を中止し、代わりに ../sealos-deploy/SKILL.md に従ってください。このモードではログインと対話型プロンプトが禁止されています。以下はすべてローカルでの対話型の手順です。

python3 scripts/sealos-api.py status

• authenticated: true の場合は次に進み、namespace と region_domain を控えてください。
• 認証されていない場合は、python3 scripts/sealos-api.py login を バックグラウンドで実行し、stderr を監視して、サインイン URL が表示されたらすぐにユーザーへ伝えてください（コードには有効期限があります。コマンドが終了するまで何もせずに待ってはいけません）。代わりに、ユーザーは Sealos のウェブコンソール（左上のアバター → kubeconfig）から kubeconfig をコピーし、~/.sealos/kubeconfig に貼り付けることもできます。
• リージョンが違う場合は login --region <url> を実行してください。ワークスペースが違う場合は workspaces と switch <name> を実行してください。

デプロイ、データベースの作成、ストレージの利用はアカウントのクォータ／残高を消費します。クォータエラーでデプロイが拒否された場合は、その旨を報告してください。数値を小さくして黙って再試行してはいけません。

デプロイの判断フロー（15 分で進める手順）

ユーザーが何かのデプロイを希望した場合は、まず分類してください。誤った手順を選ぶと、時間を使い切ってしまいます。

1. 既知のセルフホスト製品（Uptime Kuma、Metabase、n8n など）： python3 scripts/sealos-api.py store-list --search <name> を実行します。
   • ストアに該当項目がある場合 → ストアテンプレートをデプロイします（deploy.md のパス A）。 最速で実績のある方法です。約 3 分で完了します。
   • ストアに該当項目がない場合 → recipes.md で既製のレシピを確認し、なければ公式 Docker イメージを使ってテンプレートを作成します（deploy.md のパス B）。公式イメージがある場合、製品をソースからビルドしてはいけません。
2. ユーザー自身のプロジェクト（ソースコードがある）：既存の Dockerfile／compose ファイルを探し、なければ生成します。linux/amd64 向けにビルドしてプッシュし、イメージをデプロイします（build.md、続いて deploy.md のパス B）。
3. データベース／バケットのみ：databases.md／platform.md のオブジェクトストレージのセクションに従い、最小限のテンプレートとしてデプロイします。

デプロイ後は必ず、報告する前に検証してください。

bash scripts/wait-app.sh -u https://<host>.<region-domain> deployment/<name> [cluster/<name>-pg ...]

*.sealos.io のリージョンでは、ローカルデプロイ時にスクリプト内で Brain Project の申請も行われます。brain_adoption.ok が false の場合、または検証後も warnings に incompleteResourceSet が含まれている場合は、再デプロイせずに sealos-api.py adopt <instance> を実行してください。*.sealos.run ではこの処理はスキップされます（brain_adoption.reason: not-sealos-io）。deploy.md を参照してください。

すぐに使える操作

export KUBECONFIG=~/.sealos/kubeconfig
kubectl get deploy,sts,pods                                   # what's running
kubectl get clusters.apps.kubeblocks.io                       # databases
kubectl get ingress -o custom-columns='NAME:.metadata.name,HOST:.spec.rules[0].host'  # public URLs
kubectl logs deploy/<name> --tail=100                         # app logs
kubectl describe pod <pod>                                    # scheduling/pull issues
kubectl get events --field-selector type=Warning --sort-by=.lastTimestamp | tail -20
kubectl scale deploy/<name> --replicas=2                      # scale
python3 scripts/sealos-api.py store-list --search <query>     # template store

振り分け

意図	参照先
あらゆるものをデプロイする（ストアテンプレート、イメージ、ビルド済み成果物）	deploy.md
ユーザーのソースコードの Dockerfile／イメージビルド／レジストリへのプッシュ	build.md
PostgreSQL／MySQL／MongoDB／Redis／Kafka のプロビジョニングまたは接続	databases.md
テンプレート YAML 作成時のマニフェストルール（ラベル、Ingress、ストレージ、クォータの段階、オブジェクトストレージ）	platform.md
ステータス、ログ、デバッグ、スケーリング、削除、コスト管理	operate.md
人気のセルフホストソフトウェア向けアプリ別レシピ	recipes.md
Brain のマネージドサンドボックス（SEALAI_DEPLOY_MODE=managed）	../sealos-deploy/SKILL.md

タスクに必要なものだけを読み込んでください。通常は参照先 1 つ、多くても 2 つです。

実行ルール

1. 証拠なしにデプロイの成功を報告してはいけません：wait-app.sh が終了コード 0 で終了し、かつ公開 URL が実際のページを返すこと（2xx／3xx。SSR アプリの場合は、本文がエラーページではないこと）。検証に失敗した場合は、operate.md に従って原因を調査してください。むやみに再デプロイしてはいけません。
2. 本番用イメージは linux/amd64 向けにビルドしてプッシュします（docker buildx build --platform linux/amd64）。Apple Silicon のデフォルト設定では arm64 イメージが生成され、Sealos 上で exec format error が発生してクラッシュループします。
3. リソースのリクエスト／上限は、プラットフォームの段階的な基準に従います （platform.md）。リクエストは上限から導出し、メモリには必ず Mi の値を使います。
4. Template API を使ってデプロイしてください。デバッグ中に単一のリソースを扱う場合のみ kubectl apply に切り替えます。また、kubectl apply は Deployment と volumeClaimTemplates の組み合わせを受け付けないため、StatefulSet を使ってください。
5. アプリ、データベース、バケットの削除や、共有マシン上でのワークスペース切り替えなど、破壊的な操作には、事前にユーザーの明示的な確認が必要です。
6. シークレットの値を表示してはいけません。シェル変数に読み込むか、パイプで渡してください。ユーザーには名前と値の取得方法だけを示します。
7. 変更後は状態を読み戻して（kubectl get ...）、その内容を説明してください。
8. アプリ名ごとに、一度にデプロイできるのは 1 つだけです。共有 namespace 内で名前が重複すると、セレクターが機能しなくなります。ランダムなサフィックス（-a1b2c3d4）には理由があるため、保持してください。
9. エージェントのサンドボックスによってワークスペース外への書き込みがブロックされる場合は、~/.sealos/kubeconfig の書き込み、Docker ソケットの使用、およびその kubeconfig を読み取る必要があるコマンドについて、ファイルアクセス権限の拡大を求めてください。

レスポンス形式

各操作の後に、デプロイ／変更した内容（名前＋名前空間）、公開 URL（ある場合）、検証結果（準備完了の状態、HTTP コード）、認証情報の保存場所（シークレット名のみ、値は記載しない）を報告します。失敗した場合は、失敗したリソース、決定的なログ／イベント行、次に実行する対応を報告します。