volcengine-deploy

Volcengine デプロイ用スキル

ユーザーが ECS／VKE／veFaaS とリソース管理方法（cli または iac）を選択した後、ローカルのプロジェクトディレクトリまたはリモートの Git URL を Volcengine にデプロイします。デプロイの実行は実用性を重視してください。ユーザーが Terraform／IaC を選択した場合、またはすでに IaC のワークフローを使用している場合に限り、volcengine-iac を使用します。それ以外の場合は、ve CLI と .volcengine/created-resources.json を使用します。

---

0. 前提条件

Volcengine の認証は、呼び出す実行スキル（volcengine-cli、volcengine-iac、または volcengine-vefaas）で確認します。そのスキルで必要な AK／SK 環境変数、またはそのスキルが対応している場合は設定済みの CLI プロファイルを受け入れてください。ここで、スキルの必須要件を重複して定めないでください。

ユーザーがデプロイ方法を選択した後、ツールを確認します。

モード	必須ツール
ECS	ve、git、jq、curl。ユーザーがポート 22 を開く場合のみ ssh。Docker または compose でパッケージ化する場合のみ docker／docker compose
VKE	ve、docker、kubectl、git、jq、curl
veFaaS	volcengine-vefaas スキルに切り替える／呼び出す。このスキルで vefaas、Node.js、認証、フレームワークの検出、デプロイコマンドを確認します

tosutil は ECS の成果物転送と TOS バケット用のオプションです。volcengine-deploy の必須要件に追加しないでください。利用できない場合は、許可されていれば SSH／scp を使用するか、既存の成果物 URL をユーザーに確認します。

ユーザーがモードを選択していない場合は、volcengine-prepare をインラインで実行するか、次の選択をユーザーに確認します。

1. Deployment mode: ECS / VKE / veFaaS (recorded as `ecs` / `vke` / `vefaas`)
2. Resource strategy: new isolated project deploy-<repo>, or reuse existing resources
3. Resource management: CLI resource ledger / Terraform IaC (recorded as `cli` / `iac`)

永続的なローカル状態は、リポジトリのルートにある .volcengine/ に保存されます。

.volcengine/
  deployment-plan.md       # human-readable approval gate
  deploy-choice.json
  created-resources.json   # CLI fast path only
  iac-outputs.json
  terraform/               # IaC-managed resources

---

手順

この表はナビゲーションの概要です。詳細なルールは、「詳細」に記載されたセクションまたはリファレンスファイルを参照してください。

#	アクション	詳細
1	ターゲットを解決する — ローカルパスまたは Git URL を解決し、repo_name、repo_dir、git_sha を記録します。	ステージ 0
2	パスを読み込む、または選択する — .volcengine/deploy-choice.json を読み込みます。ファイルがない場合は、volcengine-prepare スキルを使用するか、mode、リソース戦略、リソース管理方法をユーザーに確認します。	ステージ 0
3	計画を作成する — ユーザーが使用する言語で .volcengine/deployment-plan.md を作成または更新します。	references/deployment-plan-template.md
4	リソースを提示する — VPC、ECS、VKE、RDS、Redis、CR、EIP、依存関係など、作成または再利用するすべてのリソースを提示します。	references/deployment-plan-template.md
5	検証ゲート — プロビジョニングの前に、status: validated、入力済みの Validation Proof、および空でない approval_evidence を伴う approval: granted を必須とします。	references/deployment-plan-template.md
6	リソース管理方法を振り分ける — Terraform／IaC には volcengine-iac スキルを使用します。それ以外の場合は、ve CLI と .volcengine/created-resources.json を使用します。	リソース管理の振り分け
7	リソースをプロビジョニングする — リソースを作成または再利用します。CLI で作成したリソースは、それぞれ .volcengine/created-resources.json に追記します。	リソース台帳
8	ランタイム設定を接続する — 設定とシークレットを解決します。シークレットは絶対に出力しないでください。	環境設定と依存関係の接続
9	デプロイを実行する — 選択したケース（ecs、vke）を実行するか、vefaas には volcengine-vefaas スキルを使用します。	分岐ごとのリファレンス
10	成功を確認する — 可能な場合は、パブリックエンドポイント、ヘルス、ログ、および主要な動作を 1 つ確認します。	分岐ごとのリファレンス
11	失敗に対処する — CLI によるクリーンアップコマンドを逆順で出力します。確認なしに再利用したリソースを削除してはいけません。	リソース台帳
12	結果を報告する — URL、ヘルス、受け入れ状況、ログ、リソース記録、クリーンアップ手順、警告を出力します。	デプロイの概要

---

1. ステージ 0 — リポジトリと選択内容の解決

input="${1:-.}"
if [[ "$input" =~ ^(https?|git@) ]]; then
  repo_name=$(basename "$input" .git)
  work_dir="/tmp/volcengine-deploy/$repo_name"
  mkdir -p "$work_dir"
  if [ -d "$work_dir/src/.git" ]; then
    git -C "$work_dir/src" pull --ff-only
  else
    git clone --depth 1 "$input" "$work_dir/src"
  fi
  repo_dir="$work_dir/src"
else
  repo_dir=$(cd "${input:-.}" && pwd)
  repo_name=$(basename "$repo_dir")
  work_dir="$repo_dir/.volcengine"
  mkdir -p "$work_dir"
fi
git_sha=$(cd "$repo_dir" && git rev-parse --short HEAD 2>/dev/null || echo "$(date +%s)")

ローカルディレクトリはその場でデプロイし、クローンしません。Git URL の場合は、まず浅いクローンを使用してください。クローンが繰り返し失敗する場合は、アーカイブ／サブディレクトリのパスを試すか、「リモートからのクイックビルドには適していません」という明確なメッセージを表示して中止してください。README／静的ミラーをデプロイ済みアプリケーションだと主張しないでください。

.volcengine/deploy-choice.json が存在する場合は読み込んでください。このファイルは volcengine-prepare によって生成され、選択内容のスキーマが正として維持されます。volcengine-deploy は選択されたリポジトリ、リージョン、モード、ポート、依存関係、データベースの選択、リソース戦略、プロジェクト、および infra_management のみを使用します。

.volcengine/deploy-choice.json がない場合は、volcengine-prepare を実行するか、ファイルを作成するために不足している選択内容のみを確認してください。このスキルで完全な選択スキーマを別途管理しないでください。

選択ファイルを読み込むか作成した後、.volcengine/deployment-plan.md を作成または更新してください。最初に references/deployment-plan-template.md を読んでください。計画本文はユーザーの元の言語で記述し、想定されるリソースを列挙してください。プロビジョニングは status: validated、approval: granted、および空でない approval_evidence を条件としてください。

approval が pending の場合は、ユーザーと同じ言語で、リソースを作成する前に確認してください。

Deploying <repo_name> via <mode> in <region>.
Resource plan:
- <create|reuse> <resource type>: <name>, <purpose/exposure/cleanup>
Proceed? [y/N]

---

2. リソース台帳

リソース台帳は、CLI で作成したリソースにのみ使用してください。IaC で作成したリソースは Terraform の状態で追跡され、.volcengine/iac-outputs.json を通じてエクスポートされます。

volcengine-deploy が作成するすべてのリソースは、作成直後に .volcengine/created-resources.json に追加する必要があります。これはクリーンアップと障害復旧のために必須です。

台帳エントリ：

{
  "type": "eip",
  "id": "eip-xxxx",
  "name": "deploy-myapp-eip",
  "region": "cn-beijing",
  "project": "deploy-myapp",
  "reused": false,
  "created_at": "2026-05-29T00:00:00Z",
  "delete_command": "ve vpc ReleaseEipAddress --AllocationId eip-xxxx"
}

ルール：

• 新規リソース：reused=false とし、正確な削除コマンドを含めてください。
• 再利用するリソース：reused=true とし、破壊的なクリーンアップの対象に含めないでください。
• EIP を ECS インスタンスと同時に作成し、そのインスタンスと一緒に解放する場合は、dependent=true / cleanup_optional=true としてマークするか、独立した台帳項目として記載しないでください。インスタンスがすでに EIP を解放していることだけを理由に、クリーンアップを失敗させないでください。
• 失敗時は、台帳の逆順でクリーンアップコマンドを表示してください。現時点では一括クリーンアップの実行コマンドはありません。ユーザーが台帳の delete_command の値を手動で確認して実行する必要があります。ユーザーの確認なしに削除しないでください。
• 新規リソースには、分離された Volcengine プロジェクト deploy-<repo> を作成または使用することを優先してください。ただし、そのプロジェクト名をリソース作成に渡す前に、プロジェクトが存在するか作成可能であることを確認してください。プロジェクトを作成できない場合は default を使用し、名前とタグでリソースを分離してください。

---

3. リソース管理のディスパッチ

デプロイ計画のゲート

クラウドリソースの作成には費用がかかり、簡単には元に戻せないため、計画のフロントマターには独立した2つの事実を記録します。

• status：draft | validated — 検証チェックに合格したかどうか。
• approval：pending | granted — ユーザーがリソース作成を承認したかどうか。
• approval_evidence：ユーザーが承認した言葉の引用。これが空の場合、approval: granted は無効です。

次の条件をすべて満たす場合にのみ、リソースを作成、変更、または再利用してください。status: validated であること、Validation Proof セクションに実際のチェックが記入され、必須チェックに失敗したものがないこと、approval: granted であること、そして approval_evidence が空でないことです。それ以外の場合は、いったん停止して、まずゲートを完了してください。

ルール：

• approval_evidence には、実行を承認するユーザーの言葉を引用する必要があります — 「just deploy it」、「open the resources for me」、「go ahead」などです。「use ecs」のような設定の選択は、選択であって費用の承認ではないため、証拠として使用してはいけません。
• 実際に承認する言葉がない状態で approval: granted に設定してはいけません。また、必須の決定事項やシークレットが不足している場合、あるいはチェックを実際に実行していない場合に status: validated に設定してはいけません。未実行のチェックは、合格したことにせず、理由とともに deferred として記録してください。
• ユーザーが自律的なデプロイを承認した場合（「deploy it for me」、「资源也帮我开好」、「go ahead and deploy」など）、リソース計画を一度提示し、その引用を添えて approval: granted に設定してから、リソースごとに確認を挟まずに進めてください。単なるモード選択ではなく、デプロイまたはリソース作成を明確に承認する言葉である場合にのみ、これを承認として扱ってください。
• 計画の主要な内容（mode、region、infra_management、またはリソース計画）が変更された場合は、status: draft、approval: pending、approval_evidence: "" にリセットし、リソース計画を再提示して、改めて確認を求めてください。

プロビジョニングの前に、.volcengine/deploy-choice.json の infra_management に基づいて処理を振り分けてください。volcengine-prepare が cli と iac の推奨およびユーザーの選択を担当し、このスキルはその結果を使用するだけです。

infra_management	アクション
iac	volcengine-iac を使用します（以下の When using IaC を参照）。
cli	ve CLI とリソース台帳を使用します（以下の When using CLI を参照）。

infra_management が存在しないか無効な場合、ここでデフォルトを推測してはいけません。volcengine-prepare に戻るか、ユーザーに cli または iac を選択してもらい、その後 .volcengine/deploy-choice.json を更新して .volcengine/deployment-plan.md を更新してください。

IaC を使用する場合：

1. .volcengine/deploy-choice.json を使って volcengine-iac を呼び出すか、そちらに切り替えてください。
2. そのスキルで Terraform の生成、検証、計画、および明示的な適用確認を実行してください。
3. VPC、サブネット、セキュリティグループ、クラスター、CR、データベース、キャッシュの出力には .volcengine/iac-outputs.json を使用してください。
4. ここでデプロイのパッケージ化とランタイムの手順を続けてください。イメージのビルド／プル、Cloud Assistant の実行、Kubernetes マニフェストの適用、マイグレーションの実行、ヘルス状態の確認を行います。

CLI を使用する場合：

1. ve でリソースを直接作成してください。
2. 作成したリソースはすべて、作成後すぐに .volcengine/created-resources.json に追加してください。
3. 失敗した場合は、逆順で実行するクリーンアップコマンドを表示してください。

---

4. 環境と依存関係の設定

ECS サービスを起動したり、Kubernetes マニフェストを適用したりする前に、実行時の設定を解決します。

1. .env.example、.env.sample、フレームワーク設定、および IaC／CLI プロビジョニングの依存関係の出力を読み取ります。
2. 機密情報ではない値は設定に、機密情報を含む値はシークレットに分けます。接続文字列、パスワード、トークン、AK/SK、セッショントークンはシークレットとして扱います。
3. 必須の値が不足している場合はユーザーに確認します。シークレットの値をユーザーに表示したり、ログに書き込んだりせず、生成したローカルファイルのモードは 0600 にします。
4. ECS systemd の場合、サービスを起動する前に /opt/<repo>/.env に書き込みます。ユニットテンプレートは EnvironmentFile=-/opt/<repo>/.env を通じてこれを読み込みます。
5. VKE の場合、解決した値から ConfigMap と Secret のマニフェストを生成します。適用する Secret に <connection-string> のプレースホルダーを残さないでください。

ヘルスチェックの前に、マネージド依存関係の設定を完了する必要があります。

• RDS データベース（database_product=rds、エンジン mysql／postgresql／sqlserver）：インスタンス、データベース、アプリケーションアカウントを新規作成または再利用し、プライベートエンドポイントを使用して DATABASE_URL を構築します。ECS／VKE のサブネット CIDR またはセキュリティグループの送信元をデータベースの許可リストに追加します。migration_paths が空でない場合は、明示的にマイグレーションを実行します。
• AIDAP データベース（database_product=aidap、エンジン supabase／postgresql）：volcengine-db-supabase を呼び出してワークスペース、ブランチ、アプリケーション DB アカウント／データベースを新規作成または再利用し、アプリケーションのヘルスチェック前にデータベース／AIDAP の環境値を返します。
• Redis：インスタンスとアプリケーションアカウント／パスワードを新規作成または再利用し、プライベートエンドポイントを使用して REDIS_URL を構築します。ECS／VKE のサブネット CIDR またはセキュリティグループの送信元を Redis の許可リストに追加します。
• 検出された依存関係に対するマネージドサービスの利用をユーザーが辞退した場合は、永続性／スケーリング上のトレードオフを伝え、選択された代替手段を同じ環境変数／Secret の経路に設定します。

---

5. ブランチのディスパッチ

case "$deploy_mode" in
  ecs)  proceed_ecs ;;
  vke)  proceed_vke ;;
  vefaas) run_vefaas_skill ;;
  *)    echo "Unknown deploy mode: $deploy_mode"; exit 2 ;;
esac

---

6. ECS ブランチ

ECS は、軽量な VM を使用するデフォルトの方法です。デプロイ後にユーザーがサービスにアクセスできるよう、パブリックサービスには EIP を割り当てる必要があります。

リポジトリの構成に基づいてパッケージング方法を選択します。Compose ファイルがある場合は ECS で Compose を使用し、Dockerfile がある場合は ECS で Docker を使用します。明確なバイナリまたは単一プロセスの場合は、バイナリと systemd を使用します。それ以外の場合は、起動コマンドについて要点を絞って 1 つ質問します。

メインコンテキストでは、次の厳格な境界を守ってください。

• infra_management=iac の場合は IaC の出力を使用します。それ以外の場合は CLI 台帳の手順を使用し、CLI で作成したリソースをすべて直ちに記録します。
• インスタンスタイプや OS イメージをハードコードしないでください。利用可能なものを照会し、GPU、WebUI、マーケットプレイス、または無関係なイメージが返される曖昧なイメージ検索は避けます。
• SSH 22 が明示的に許可されていない場合は、閉じたままにして Cloud Assistant を使用します。SSH が許可されている場合は、可能であれば現在の外向き IP に制限します。
• Volcengine RunCommand は非同期です。コマンドが成功したと判断する前に、実行結果をポーリングします。
• 生成した一時的な ECS パスワードを表示したり、台帳／状態に書き込んだりしてはいけません。
• リスニングポート、ローカルのヘルスチェック／ルートパス、パブリックエンドポイント、ログ、および可能であればアプリケーションの主要な動作を検証します。

ECS のパッケージング、アップロード、Cloud Assistant、Docker ミラー、アーキテクチャ、ヘルスゲート、クリーンアップの詳しい手順については、references/ecs-deploy-steps.md を参照してください。

---

7. veFaaS ブランチ

ここに veFaaS のデプロイ手順を重複して記載しないでください。ユーザーが veFaaS を選択した場合は、次の情報を指定して volcengine-vefaas スキルに切り替えるか、呼び出します。

• リポジトリのパス
• アプリ名
• リージョン
• 判明している場合は、検出されたフレームワーク／ポート
• 環境変数に関するメモ
• prepare からの警告

volcengine-vefaas スキルが vefaas inspect を実行し、ログインを検証して、アプリを作成／リンクし、必要に応じて環境変数を設定してデプロイし、ドメインを表示することをユーザーに伝えます。

volcengine-vefaas スキルが失敗した場合は、このメインのデプロイフローに戻ります。失敗の概要を伝えたうえで、次のいずれかをユーザーに選んでもらいます。

• veFaaS の問題を修正して再試行する
• ECS に切り替える
• VKE に切り替える

---

8. VKE 分岐

VKE リソースのプロビジョニングには、クラスター、ノードプール、CR、LB、およびマネージド依存関係で plan/diff/destroy による安全性が役立つため、volcengine-iac を推奨します。トレードオフを確認したうえでユーザーが CLI を選択した場合、一時的な検証、明示的なユーザーの希望、または IaC のフォールバックには、リソース台帳と併せて ve CLI を使用します。

VKE を選択したら、docker、kubectl、ve、および IaC を使用する場合は terraform/jq を確認します。ノードのアーキテクチャに合わせてビルドします。クラスターのデータで別の値が確認できない限り、デフォルトは linux/amd64 とし、ロールアウト前にプッシュしたイメージのプラットフォームを確認します。

以下の順序付き実行手順を維持します。これらのアクションは順番に実行する必要があり、前のステップが収束する前に後のステップを実行することが、VKE で最もよくある失敗の原因です。

1. VKE と CR をプロビジョニングするか、既存のものを再利用します（IaC の出力または CLI の高速パス）。
2. クラスターが Running になるまで待ってから、kubeconfig を取得します（IaC の出力または CreateKubeconfig を使用）。
3. アドオンを確認します。core-dns が存在することを確認し、プライベート CR からのプルには cr-credential-controller を推奨します。
4. ノードのアーキテクチャに合わせてイメージをビルドします。
5. CR に認証してイメージをプッシュし、プッシュしたイメージのプラットフォームを確認します。
6. env/Secret の値と依存関係の出力を解決します。
7. 解決済みの値からマニフェストを生成します。
8. マイグレーションのパスがある場合は、Kubernetes Job としてマイグレーションを実行します。
9. 適用してから、ロールアウトと LoadBalancer/EIP を待ちます。
10. パブリックエンドポイントと、アプリの主要な動作を 1 つ確認します。

メインコンテキストでは、以下の厳守事項を維持します。

• 利用可能な場合は、VPC/サブネット/セキュリティグループ/VKE/CR の IaC 出力を使用します。それ以外の場合は、CLI の高速パスで作成または再利用し、リソースを記録します。
• クラスターが Running になる前に CreateKubeconfig を実行すると OperationDenied が返されます。先にポーリングして Running になるのを待ちます。
• クラスター内 DNS に依存する前に、core-dns を確認します。
• プライベート Volcengine CR イメージをプルする際は、アプリのマニフェストにレジストリのパスワードを保存するのではなく、cr-credential-controller を推奨します。
• docker login には、GetAuthorizationToken から Result.Username を再取得して使用します。代替のユーザー名を決して捏造しないでください。
• ワークロードを適用する前に ConfigMap/Secret の値を解決します。適用する Secret マニフェストにプレースホルダーを残さないでください。
• マイグレーションのパスがある場合は、Kubernetes Job としてマイグレーションを実行します。
• ロールアウトと LoadBalancer/EIP を待ってから、パブリックエンドポイントを確認します。

マネージド依存関係には、実用上可能な場合はマネージド Volcengine サービスを推奨します。それ以外の場合は、ステートフルコンテナを VKE 内にデプロイする計画であることを明確に説明します。

完全な VKE パイプライン（クラスターの待機、kubeconfig、アドオンの確認、CR 認証/プッシュ、ロールアウト、エンドポイントの確認）については、references/vke-deploy-steps.md を参照してください。マニフェストのテンプレートについては references/k8s-manifests.md、イメージビルドのテンプレートについては references/dockerfile-templates.md を参照してください。

---

9. デプロイの概要

アクセスカードを 1 つ表示します。

volcengine-deploy — <repo_name> (<git_sha>)

Mode:        <ecs|vke|vefaas>
Region:      <region>
Project:     <deploy-project or reused resources>
URL:         <public endpoint>
Health:      <checked URL/status>
Acceptance:  <core app behavior checked, or reason only transport health was possible>
Resources:   .volcengine/created-resources.json
IaC:         <.volcengine/terraform + .volcengine/iac-outputs.json | n/a>
Logs:        <journalctl / docker logs / kubectl logs / vefaas logs command>
Cleanup:     <reverse-order cleanup commands or ledger path>
Notes:       <credentials/env/migration warnings>

ユーザーからの依頼がない限り、カスタムドメイン、HTTPS、ダッシュボード、コストカードは追加しないでください。これらはデプロイ後の運用タスクです。

---

10. 参考情報

必要に応じて、以下の参考資料を使用します。

• プロビジョニング前に必ず確認：デプロイ計画テンプレート、ゲート、リソース計画（references/deployment-plan-template.md）
• ECS のビルド/systemd/アップロードの詳細：references/ecs-deploy-steps.md
• VKE デプロイパイプライン（クラスター/kubeconfig/アドオン/CR/ロールアウト）：references/vke-deploy-steps.md
• veFaaS デプロイの引き継ぎに関する詳細：references/faas-deploy-steps.md
• Dockerfile のテンプレート：references/dockerfile-templates.md
• Kubernetes マニフェスト：references/k8s-manifests.md
• ランタイム依存関係：references/supported-dependencies.md

---

11. よくある失敗例

よくある注意点は、メインのスキルを状況に応じて使えるよう、参照資料としてあえてまとめています。

• ECS インスタンス／イメージ／Cloud Assistant／SSH／Docker ミラーの問題：references/ecs-deploy-steps.md
• コンテナーのアーキテクチャと Dockerfile の落とし穴：references/dockerfile-templates.md
• VKE パイプラインの手順（kubeconfig／アドオン／CR 認証／ロールアウト）：references/vke-deploy-steps.md
• Kubernetes の Readiness、LoadBalancer、プローブ、マニフェストの問題：references/k8s-manifests.md
• マネージド依存関係の接続とマイグレーション：references/supported-dependencies.md
• veFaaS CLI／認証／フレームワークのセットアップ：references/faas-deploy-steps.md および volcengine-vefaas
• デプロイ中の権限／ロール／STS エラー：volcengine-troubleshooting スキルを有効にし、そのアカウント権限診断機能を使って根本原因を特定し、修正手順をユーザーに案内します。