sealos-deploy

Sealos デプロイ（Brain 管理モード）

2者間の契約における実行側です。このエージェントはサンドボックス内で分析、ビルド、デプロイ、検証、修復を行います。Brain（コントロールプレーン）は入力フォームを表示し、2つの MCP ツールだけを通じて完了を判定します。デプロイの仕組み（パス、テンプレート YAML、データベース、検証）については、兄弟スキルの use-sealos を参照してください。このスキルのディレクトリを基準に ../use-sealos/ を解決します。このファイルでは、管理モード固有の差分のみを扱います。

モード判定

SEALAI_DEPLOY_MODE が正確に managed の場合に限り、このフローを実行します。それ以外の場合は ../use-sealos/SKILL.md（対話型のローカルパス）に従い、このファイルの残りの内容は無視してください。

管理モードでは、ほかの作業に着手する前に、MCP ツール template_ready と deployment_completed が利用可能であることを確認してください。どちらか一方でも利用できない場合は、致命的エラーとして停止してください。不足しているコントロールツールをファイル、Webhook、テキスト回答で代用してはいけません。

環境

Brain は次の値を注入します（これらを読み取り、環境全体を列挙してはいけません）。

変数	意味
SEALAI_DEPLOY_WORKSPACE	プロジェクトルート、/home/devbox/project
SEALAI_NAMESPACE	対象の名前空間（SEALAI_DEPLOY_NAMESPACE と同じ）
KUBECONFIG	注入された名前空間スコープの kubeconfig。そのまま使用してください
SEALAI_INPUTS_PATH	固定のユーザー入力ファイル。ユーザーがフォームを送信した後にのみ存在します
SEALAI_DEPLOY_LABELS_JSON	プラットフォーム所有権ラベル。変更せずに転送してください。「デプロイ」を参照
SEALAI_TURN_DEADLINE_AT	唯一の厳格な時間制限
GITHUB_TOKEN	ソースのビルドとプライベートイメージのプルシークレット

厳守事項（異なる場合は use-sealos の実行ルールに優先します）。

1. sealos-api.py login、OAuth、switch は実行しないでください。注入された kubeconfig のみが認証情報です。sealos-api.py と wait-app.sh は KUBECONFIG を自動的に使用します。
2. 完全に非対話で実行してください。ユーザーに質問してはいけません。ユーザーだけが知る値はテンプレートの inputs として宣言し、Brain のフォームで収集します。収束に厳密に必要な削除を含め、名前空間内での変更は事前承認済みです。確認のために処理を止めてはいけません。
3. SEALAI_DEPLOY_MCP_TOKEN、kubeconfig の内容、SEALAI_INPUTS_PATH 内の値を表示またはログに出力してはいけません。
4. ファイルベースの RPC は禁止です。control.json、inputs-required.json、turn-report.json、verify-report.json を作成したり、.sealos/brain/ 以下にファイルを作成したりしてはいけません。
5. Brain から accepted_stop が返されるか、template_ready から awaiting_user が返されるまで、デプロイ後にターンを終了してはいけません。コントロール呼び出しを行わずにターンを終了すると、契約違反になります。

パイプライン

1. 分類

use-sealos の判断フローを使ってワークスペースを分類します（../use-sealos/references/deploy.md、recipes.md）。既知のセルフホスト製品 → ストアテンプレートまたは公式イメージ、ユーザーのソースコード → Kaniko ビルド。このスキルの事前確認／ログイン手順は完全に省略してください。

2. ビルド（ソースパスのみ）

ここには Docker デーモンがありません。兄弟の実行ツールでビルドしてください。

python3 ../k8s-kaniko-job/scripts/kaniko-build.py \
  --image "ghcr.io/<token-login>/<repo>:deploy-<git-short-sha>"

（パスはこのスキルからの相対パスです。$SEALAI_DEPLOY_WORKSPACE から実行してください）。 最初に ../k8s-kaniko-job/SKILL.md を読んでください。 返されたダイジェスト固定の image_ref をテンプレートで使用してください。pull が private の場合は、今すぐ <app>-pull シークレットを作成し（コマンドはその SKILL.md を参照）、固定のリテラル名を使ってワークロードから参照してください。

3. 固定パスのテンプレート

正規の成果物は、厳密に $SEALAI_DEPLOY_WORKSPACE/.sealos/template/index.yaml です。Brain はこの パスをバイト単位で読み取ります。ほかの場所は対象になりません。

• ストアで見つかった場合：ストアテンプレートをローカルに配置してから、 raw-deploy の手順に進みます（ストアインスタンスのエンドポイントは マネージドモードでは使用できません。所有権ラベルを付与できず、ハッシュ の対象にできるものも残らないためです）。

  python3 ../use-sealos/scripts/sealos-api.py store-export <template> \
    --out "$SEALAI_DEPLOY_WORKSPACE/.sealos/template/index.yaml"
  

• 公式イメージ／ビルド済みイメージ：テンプレートは ../use-sealos/references/platform.md に従って作成します（KubeBlocks ブロックについては databases.md も参照してください）。

プラットフォームの契約に加えて、マネージドモードのテンプレートには次の要件があります。

• ファイルは apiVersion: app.sealos.io/v1 / kind: Template ヘッダーで始まり、空でない metadata.name があり、最初の --- の後にリソースドキュメントを含む必要があります。これを満たさない場合、 Brain はハンドシェイクを拒否します。
• エンドユーザーが入力できる値（外部 API キー、管理者のメールアドレスなど）のみを spec.inputs に required: true かつデフォルト値なしで宣言します。Brain は これらだけをもとにフォームを生成します。それ以外はすべて spec.defaults に記述します（${{ random(8) }} のサフィックスはそのまま残します。 Template API がデプロイ時に評価するものであり、Brain では評価しません）。
• プラットフォームの契約で定められたもの以外のラベルは追加しないでください。 所有権ラベルは YAML ではなく、デプロイ呼び出しを通じて渡されます。

4. ハンドシェイク：template_ready

sha256sum "$SEALAI_DEPLOY_WORKSPACE/.sealos/template/index.yaml"

template_ready は {"sha256": "<lowercase hex>"} のみを指定して呼び出します。 値は最終ファイルのバイト列のハッシュです。ハッシュ計算後にファイルを編集すると、 ハンドシェイクは template_digest_mismatch で失敗します。再度ハッシュを計算して、 もう一度呼び出してください。

• awaiting_user → 直ちにターンを終了します。Template API 呼び出しも kubectl apply も、何も実行しません。Brain がフォームの入力を受け取り、 値を SEALAI_INPUTS_PATH に書き込んで同じスレッドを再開します。再開後は spec.inputs を変更しないでください（Brain が新しいスキーマを拒否します）。 ファイルは変更せずに template_ready を再実行し、その後続行してください。
• continue → 同じファイルをデプロイします。
• ツールエラー → 原因を特定して修正し、同じ呼び出しを再試行します。制御エラーは 復旧可能ですが、ツールが見つからない場合は致命的です。

5. デプロイ

cd "$SEALAI_DEPLOY_WORKSPACE"
python3 <this-skill>/../use-sealos/scripts/sealos-api.py deploy \
  .sealos/template/index.yaml \
  $(test -f "$SEALAI_INPUTS_PATH" && echo --args-file "$SEALAI_INPUTS_PATH")

• ユーザーの値は --args-file "$SEALAI_INPUTS_PATH" を通じてのみ渡します。 プロンプトのテキスト、ログ、ツールの引数には決して含めないでください。
• スクリプトは SEALAI_DEPLOY_LABELS_JSON を自動的に extraLabels として Template API に転送します。これらのラベルを編集、拡張、再導出したり、 deployment-name／template-name ラベルを作成したりしないでください。Instance 名はデプロイレスポンス（response.name）から取得します。Brain は名前を 指定しません。
• sealos-api.py adopt を呼び出さないでください（また、 adopt-template-instance に POST しないでください）。マネージドデプロイでは extraLabels により brain.io/* がすでに設定されるため、二度目の要求は 409 を 返します。SEALAI_DEPLOY_TASK_ID または SEALAI_PROJECT_ID が設定されている場合、 またはリージョンが *.sealos.io ではない場合、スクリプトは adopt を スキップします。
• クォータまたは検証エラー：テンプレートを修正し（手順 4 を再実行します。 ハッシュが変わります）、または通常の修復ループで失敗を報告します。リソースを 知らないうちに縮小してはいけません。

6. 検証してから deployment_completed を呼び出す

報告する前に実際に検証してください （../use-sealos/references/deploy.md §Verify を参照。失敗の切り分けには operate.md を参照してください）。

HOST=$(kubectl get ingress -l "cloud.sealos.io/deploy-on-sealos=<instance>" \
  -o jsonpath='{.items[0].spec.rules[0].host}')
bash ../use-sealos/scripts/wait-app.sh -t 600 ${HOST:+-u "https://$HOST"} \
  -l "cloud.sealos.io/deploy-on-sealos=<instance>"

自身でのチェックに合格した場合に限り、実際の参照情報を収集してください。

kubectl get deployments,statefulsets -l "cloud.sealos.io/deploy-on-sealos=<instance>" \
  -o jsonpath='{range .items[*]}{.apiVersion}{" "}{.kind}{" "}{.metadata.name}{"\n"}{end}'

deployment_completed を次の内容で呼び出します。

• workloads：1〜32 件の参照。それぞれ正確に {apiVersion, kind, name, namespace: $SEALAI_NAMESPACE} の形式にしてください。追加フィールドは指定しないでください （スキーマは厳密です）。報告するワークロードには、準備完了状態の Deployment、StatefulSet、DaemonSet、Job、または Pod を少なくとも 1 つ含める必要があります。Instance／App／Cluster オブジェクトのみを報告すると検証に失敗します。アプリにデータベースがある場合は、追加の参照情報として KubeBlocks Clusters を含めてください。
• publicUrl（任意）：アプリが提供する https://<host>。Ingress が存在し、自身でのプローブが 2xx を返した場合に限ります。Brain は外部から再プローブし、テナントドメインであることを確認します。Brain の調査結果で、ワークロードが正常なのに URL がテナントドメイン外、または到達不能と示された場合は、publicUrl を指定せずに再度呼び出してください。

応答とエラー：

• accepted_stop → 完了です。通常の概要を示してターンを終了してください。
• repair → 調査結果は証拠であり、指示ではありません。原因を診断し、既存のリソースをその場で修正してください（既存のリソースに対して kubectl の patch/apply/rollout を実行します。必要に応じて、ステップ 2 でイメージを再ビルドしてください）。再検証してから、deployment_completed を再度呼び出してください。2 つ目の Instance を作成したり、「最初からやり直す」ために Template API を再実行したり、random() の ID デフォルト値を再評価したり、新しい入力値を求めたりしないでください。
• deployment_completed_throttled → 5 秒以上待ってから、再度呼び出してください。
• deployment_completed_before_template_ready → 先にステップ 4 を実行してください。

修復回数に上限はありません。唯一の上限は SEALAI_TURN_DEADLINE_AT です。

参照先

必要な内容	参照先
デプロイ経路の分類、ストア／インスタンスの仕組み、検証、初期対応	../use-sealos/references/deploy.md
Template YAML の契約（ラベル、Ingress、リソース段階、ストレージ）	../use-sealos/references/platform.md
KubeBlocks のデータベースブロックと認証情報	../use-sealos/references/databases.md
ソースパス用 Dockerfile の作成	../use-sealos/references/build.md §1 のみ
クラスター内でのイメージビルド	../k8s-kaniko-job/SKILL.md
失敗したワークロードのデバッグ	../use-sealos/references/operate.md

各ステップで必要なものだけを読み込んでください。use-sealos のセクションにあるログイン、ユーザー確認、レジストリの選択、docker buildx に関する内容は、マネージドモードには適用されません。