aspire-deployment

Aspire のデプロイ

Aspire アプリケーションのデプロイを公開、プレビュー、検証、実行、または取り消すタスクでは、このスキルを使用します。このスキルは Aspire のデプロイ先へのルーティングを担当します。ワークスペースが Aspire アプリかどうかを確認するまでは、汎用的な Azure、Docker、Kubernetes、Helm、または Bicep のワークフローを開始しないでください。

Aspire のデプロイは AppHost モデルから開始します。aspire deploy、aspire publish、aspire destroy、aspire do、および AppHost 内のデプロイ環境リソースを主要な方法として扱います。安定版 SDK／ホスティングパッケージはプロジェクトのリリース系列に合わせて使用し、Kubernetes や Radius などプレビュー限定の統合には、対応するプレビュービルドを使用します。

これは、デプロイ先ごとのリファレンスを備えた 1 つのスキルとして扱います。見つかったデプロイ先、またはユーザーが指定したデプロイ先に一致するリファレンスファイルのみを読み込みます。

ルーティングの優先順位

次の両方の条件に当てはまる場合、このスキルは汎用的なクラウドデプロイスキルより優先されます。

1. ユーザーが、デプロイ、公開、デプロイ成果物の生成、Bicep／Helm／Compose／CDK 出力の作成、Azure または AWS でのホスティング、Azure、AWS、Kubernetes、Docker Compose、または Radius へのデプロイ、デプロイ済みリソースの取り消し、またはデプロイの検証を依頼している。
2. ワークスペースに Aspire の目印がある。
   • Aspire ワークスペースの設定
   • C# または TypeScript の AppHost ファイル
   • AppHost プロジェクト
   • Aspire の分散アプリケーションビルダー API を使用する AppHost コード

Aspire の目印があるのにこのスキルが自動的に呼び出されなかった場合は、続行する前にこのスキルへ切り替えてください。ワークスペースの把握には、aspire ls、aspire config list、aspire ps、aspire describe などの Aspire CLI コマンドを優先してください。

基本原則

デプロイコードを変更する前に Aspire のドキュメントを確認する

対象パッケージを追加する前、AppHost を編集する前、または使い慣れていないデプロイ API を使用する前に、Aspire のドキュメントを確認してください。

aspire docs search "deploy with Aspire"
aspire docs search "Docker Compose deployment"
aspire docs search "Kubernetes deployment"
aspire docs search "Azure Container Apps deployment"
aspire docs search "Azure App Service deployment"
aspire docs search "Azure Kubernetes Service deployment"
aspire docs search "Radius deployment"
aspire docs get "deploy-to-azure-kubernetes-service-aks"
aspire docs get "<slug-from-search-results>"

C# または TypeScript の API の正確な形を確認する必要がある場合は、API ドキュメントも参照してください。リポジトリでどちらの言語の AppHost が使われているか不明な場合は、両方の言語を検索してください。

aspire docs api search "<deployment API or concept>" --language csharp
aspire docs api search "<deployment API or concept>" --language typescript
aspire docs api get "<id-from-api-search>"

パッケージ名、ビルダーメソッド、オーバーロード、またはデプロイコマンドを推測しないでください。API の形は、C# と TypeScript の AppHost で異なります。

Aspire ネイティブのデプロイを優先する

AppHost プロセス自体ではなく、AppHost で宣言されたリソースをデプロイしてください。 Docker Compose の場合は Compose 環境を構成し、Aspire にそれらのリソース用のサービスを生成させます。AppHost の Dockerfile や Compose サービスに置き換えないでください。

まず Aspire のデプロイ先と CLI コマンドを使用してください。

aspire publish --list-steps
aspire deploy --list-steps
aspire publish
aspire deploy
aspire destroy
aspire do <step>

対象固有のツールは、Aspire が成果物を生成した後、または対象のドキュメントで必要とされる場合にのみ使用してください。

• Docker Compose：生成された aspire-output/docker-compose.yaml と .env* を確認します。Aspire は aspire deploy を通じて docker compose up を実行することもできます。
• Kubernetes：生成された Helm チャートの出力を確認します。公開済みの成果物を自分で適用する場合は、Helm／kubectl を使用します。
• Azure：aspire add <azure-target>、aspire publish、および AppHost のデプロイ環境を通じた aspire deploy を使用します。
• AWS：aspire add aws を使用して統合を追加し、生成された CDK／CloudFormation の出力を確認して、AWS 統合リポジトリのガイダンスに従います。
• Radius：Aspire.Hosting.Radius はプレビューとして扱います。統合／ドキュメント検索でパッケージと API を確認してから、AddRadiusEnvironment(...).WithNamespace(...) をモデル化します。

デプロイ先が曖昧な場合にのみ確認する

ユーザーが Docker Compose、Kubernetes、Azure Container Apps、Azure App Service、Azure Kubernetes Service（AKS）、AWS などのデプロイ先をすでに選択している場合は、デプロイ先を尋ねないでください。選択されたデプロイ先を使用し、そのリファレンスに沿って続行してください。

ユーザーがデプロイ先を明示的に選択しておらず、AppHost にデプロイ環境がちょうど 1 つ含まれていない場合は、統合の追加、AppHost の編集、成果物の公開、デプロイを行う前に、デプロイ先を尋ねてください。次の単一の選択式の質問を使用してください。

この Aspire アプリをどこにデプロイしますか？

次の選択肢を表示してください。

選択肢	Aspire の追加コマンド	使用する場合
Docker Compose	aspire add docker	Docker または Podman でのローカル／サーバーコンテナデプロイ用の成果物が必要な場合。
Kubernetes	aspire add kubernetes	既存の Kubernetes クラスターがあり、Helm／Kubernetes の成果物またはクラスターへの直接デプロイが必要な場合。
Azure Container Apps	aspire add azure-appcontainers	分散アプリやサービス向けの Azure マネージドコンテナプラットフォームが必要な場合。
Azure App Service	aspire add azure-appservice	App Service モデルに適した Web アプリ／API を Azure でホスティングしたい場合。
Azure Kubernetes Service (AKS)	aspire add azure-kubernetes	Aspire を使って Azure マネージド Kubernetes をプロビジョニングし、デプロイしたい場合。
AWS	aspire add aws	Aspire と AWS CDK の統合を通じて公開／デプロイしたい場合。

プレビュー版の Radius を既定の選択肢として提示しないでください。ユーザーが Radius を明示的に希望する場合、または AppHost に Radius 環境がすでに含まれている場合に使用してください。

ユーザーが「Azure」とだけ述べた場合は、Azure の選択肢である Azure Container Apps、Azure App Service、Azure Kubernetes Service（AKS）のみを提示して、もう一度尋ねてください。AppHost にデプロイ環境がちょうど 1 つ含まれており、ユーザーがデプロイ先の変更を求めていない場合は、そのデプロイ先を使用し、検出した内容をユーザーに伝えてください。

意図が明示されていない場合は、クラウドリソースの作成前に確認する

クラウドへのデプロイでは、課金対象のリソースが作成されることがあります。ユーザーが計画、プレビュー、検証、または「デプロイ可能にする」ことを求めている場合は、デプロイ計画／成果物の作成までにとどめ、リソースをプロビジョニングするコマンドを実行する前に確認してください。

ユーザーが今すぐデプロイするよう明示的に依頼した場合は、事前チェックとデプロイを続行します。ただし、プロビジョニング前に、デプロイ先の選択、サブスクリプション／リソースグループの曖昧さ、または不足しているパラメーターに関する決定事項を必ず提示してください。

Azure のデプロイは Aspire ネイティブの手順を維持する

このスキルでの Azure デプロイ手順は、aspire add <azure-target>、AppHost 環境の構成、aspire publish、aspire deploy です。Azure デプロイ作業を、別の Azure デプロイツールや生成されたインフラストラクチャワークフローに振り分けないでください。

Aspire パッケージは同じリリース系列にそろえる

公開またはデプロイの前に、Aspire.AppHost.Sdk とホスティングパッケージが、プロジェクトで選択されたリリース系列内で互換性のあるバージョンを使用していることを確認してください。プレビュー専用の統合では、aspire add または統合のドキュメントで選択した、互換性のあるプレビュービルドが必要です。 CLI のバージョンによって、互換性のないホスティングパッケージが安全になるわけではありません。異なるバージョンが混在した依存関係グラフでは、起動時に MissingMethodException または TypeLoadException が発生する可能性があります。

デプロイコードを編集する際は、非推奨の 13.5 の構成要素を移行してください。

• ホスティングコンテキストの .ServiceProvider ではなく .Services を使用する。
• PublishAsConnectionString ではなく AddConnectionString を使用する。
• 非推奨の Aspire.Hosting.GitHub.Models リソースを Azure AI Foundry に移行する。

既定のワークフロー

1. Aspire ワークスペースを確認します。
   • まず aspire ls を実行して、現在のスコープにある AppHost を一覧表示します。さらに情報が必要な場合は、aspire.config.json、AppHost のプロジェクトファイル、または aspire ps を使用します。
   • AppHost が存在しない場合は、デプロイ作業を中止し、続行する前に aspireify スキルを呼び出して AppHost を初期化し、接続します。
   • AppHost が C# か TypeScript かを特定します。
   • 検出と状態の確認には、Aspire CLI コマンドを優先して使用します。
2. デプロイ先を確認するか、推測します。
   • ユーザーが Docker Compose、Kubernetes、Azure Container Apps、Azure App Service、Azure Kubernetes Service (AKS)、または AWS を指定した場合は、再確認せずに該当するターゲットのリファレンスを読み込みます。
   • ユーザーが「デプロイ」とだけ指定した場合は、既存の AppHost ターゲット環境リソースを確認します。
   • ターゲット環境がちょうど 1 つ存在する場合は、それを使用し、検出したことを伝えます。
   • 複数のターゲットが存在する場合、ターゲットが存在しない場合、またはユーザーが「Azure」とだけ指定した場合は、上記の選択肢を提示してデプロイ先を尋ねます。
3. ターゲットとアプリの種類に関するリファレンスを読み込みます。
   • Docker Compose：references/docker-compose.md
   • Kubernetes および Azure Kubernetes Service (AKS)：references/kubernetes.md
   • Azure Container Apps／App Service／Azure Kubernetes Service (AKS)：references/azure.md
   • AWS：references/aws.md
   • Radius プレビュー：最新の Aspire ドキュメントを確認し、Aspire.Hosting.Radius を検索します。 実験的な API の形式を推測してはいけません。
   • JavaScript アプリのリソース：references/javascript.md
   • CI/CD または GitHub Actions の自動化：references/cicd.md
4. Aspire ドキュメントを検索して、最新のガイダンスを確認します。
   • ターゲットのデプロイに関するドキュメントを検索して取得します。
   • AppHost コードを編集する前に、API ドキュメントを検索します。
5. ターゲットに応じたコード変更を適用します。
   • 統合が不足している場合は、ターゲットの aspire add ... コマンドを実行します。
   • AppHost にデプロイ環境リソースを追加します。
   • 一般的な単一環境のケースでは、明示的なコンピューティング環境の割り当てを追加しないでください。AppHost に複数のデプロイ環境がある場合に限り、割り当て先を明確にします。C# では通常 WithComputeEnvironment(...) を使用します。TypeScript の AppHost では、同等の機能があると想定する前に、現在の言語別ドキュメントを確認してください。
   • エンドポイントの公開、Helm の設定、Compose ファイルのカスタマイズ、Azure サイト／コンテナーアプリのカスタマイズ、AWS の発行ターゲットのオーバーライドなど、デプロイに必要なターゲット固有のカスタマイズ API のみを追加します。
6. デプロイモデルを事前に確認します。
   • ターゲット統合パッケージが AppHost に存在することを確認します。
   • AppHost にターゲット環境リソースがあることを確認します。
   • コンピューティング環境が複数ある場合に限り、コンピューティングリソースがターゲット環境に割り当てられていることを確認します。一般的なのは単一のコンピューティング環境で、この場合は割り当て先を推測できます。
   • パラメーター、シークレット、接続文字列、外部エンドポイント、コンテナーレジストリ、ターゲット固有の前提条件を一覧にします。
   • Azure または AWS の場合は、認証、ターゲットアカウント／サブスクリプション、リージョン／場所、リソースグループ／スタックのコンテキストを確認します。
7. 適用前にプレビューします。
   • aspire publish --list-steps または aspire deploy --list-steps を実行します。
   • 成果物のレビューが求められている場合は、aspire publish -o <scratch-or-output-path> を使用します。
   • 発行された成果物はプレビューまたは引き継ぎ用として扱います。aspire deploy は AppHost モデルから値を解決してデプロイを適用するものであり、以前に発行された出力ディレクトリを使用するものではありません。
   • リソース、エンドポイント、パラメーター、シークレット、ID、生成された成果物をまとめます。
8. デプロイするか、引き継ぎます。
   • ユーザーがデプロイを依頼し、事前確認が完了している場合は、aspire deploy を実行します。
   • aspire do <step> で名前付きステップを実行するのは、ユーザーが特定のパイプラインステップを依頼した場合に限ります。
   • 発行された成果物については、ターゲット固有の適用手順を説明します。
9. 明示的に依頼された場合に限り、破棄します。
   • aspire destroy を実行して、選択した AppHost／環境のターゲット破棄パイプラインを実行します。
   • 実行する前に、AppHost、環境、ターゲットアカウント／サブスクリプション／クラスター、および破壊的な操作を行う意図を確認します。
   • ユーザーまたは CI ワークフローによって、ティアダウンの意図がすでに明示されている場合に限り、--yes を使用します。
   • ティアダウンの失敗をトラブルシューティングする場合、または管理外の残存物をクリーンアップする場合を除き、ターゲット固有の削除コマンドより aspire destroy を優先します。
10. 結果を検証します。

• ターゲットに応じて、ターゲットの出力、aspire describe、クラウド CLI、Docker Compose、kubectl、またはエンドポイントのチェックを使用します。
• 破棄後は、ターゲットのリソースが削除されたことを検証するか、手動でのクリーンアップが必要な残存物を記録します。

AppHost のターゲット検出

AppHost でデプロイ環境リソースを検索します。

ターゲット	Aspire の追加コマンド	統合	AppHost の環境コンセプト
Docker Compose	aspire add docker	Docker ホスティング	Docker Compose 環境
Kubernetes	aspire add kubernetes	Kubernetes ホスティング	Kubernetes 環境
Azure Container Apps	aspire add azure-appcontainers	Azure Container Apps ホスティング	Azure Container Apps 環境
Azure App Service	aspire add azure-appservice	Azure App Service ホスティング	Azure App Service 環境
Azure Kubernetes Service (AKS)	aspire add azure-kubernetes	Azure Kubernetes ホスティング	Azure Kubernetes Service (AKS) 環境
AWS	aspire add aws	AWS ホスティング	AWS CDK 環境
Radius（プレビュー）	aspire integration search radius で検索	Aspire.Hosting.Radius	Radius 環境

この表はあくまで参考として使用してください。コードを編集する前に、AppHost の言語に対応する Aspire ドキュメントで現在の API を確認してください。

パラメーターとシークレットの事前確認

パラメーターはデプロイ時の入力値です。ターゲットやコマンドに応じて、構成ファイル、ユーザーシークレット、環境変数、コマンドライン引数、対話形式のプロンプト、CI/CD のシークレットストアから指定できます。

デプロイ前に、以下を報告してください。

• 構成に基づくパラメーターを含む、AppHost のパラメーター API におけるパラメーター名
• シークレットかどうか
• Parameters__name など、想定されるプロバイダーの構文。ハイフンを含むパラメーター名では、環境変数内のハイフンをアンダースコアに置き換えます。たとえば、registry-endpoint は Parameters__registry_endpoint になります
• プロジェクトの環境変数、接続文字列、Key Vault シークレット、Helm Secret、Compose .env、Azure アプリ設定など、値の受け渡し先
• 値が設定済みか、未設定か

適切な場合は AppHost のユーザーシークレットに aspire secret list を使用します。ただし、シークレットの値は出力しないでください。デプロイ成果物については、シークレットの内容をそのまま確認せず、生成されたプレースホルダーとマッピングを調べてください。

ターゲットのリファレンス

• references/docker-compose.md - Docker Compose ターゲット、生成ファイル、環境変数、クリーンアップ。
• references/kubernetes.md - Kubernetes と Azure Kubernetes Service (AKS) のターゲット選択、Helm 出力、レジストリ要件、kubectl／Helm の確認。
• references/azure.md - Azure のターゲット選択、Azure 設定、Container Apps、App Service、Azure Kubernetes Service (AKS)。
• references/aws.md - AWS のターゲット選択、AWS CDK の前提条件、発行／デプロイのワークフロー、AWS 統合ドキュメント。
• references/javascript.md - Vite／静的アセット、Node／SSR サーバー、Next.js、ゲートウェイ／バックエンドの配信パターンを含む、JavaScript アプリのデプロイモデル。
• references/cicd.md - Aspire の発行／デプロイ、パラメーター、シークレット、レジストリ認証、クラウド認証に関する CI/CD および GitHub Actions のワークフローガイダンス。
• references/preflight.md - 共通の事前確認、プレビュー、パラメーター、破棄、検証のチェックリスト。
• aspire-13-5-breaking-changes.md - 13.5 のパッケージ、API、CLI の移行ルール。

エージェントの実行

CI、スクリプト、エージェントによる操作など、無人で実行する場合は、プロンプトが表示される可能性のあるすべての Aspire CLI 呼び出しに --non-interactive を追加してください。特に、aspire publish、aspire deploy、aspire destroy では必ず追加してください。aspire destroy では、ユーザーが破棄の意図を明示的に確認した後（または CI ワークフローにその意図がすでに組み込まれている場合）に限り、--yes も渡してください。

無人実行が停止しないよう、プロンプトの表示につながる値（対象のサブスクリプション／リージョン／リソースグループ、パラメーター、シークレット、レジストリの認証情報）は、事前に指定することを推奨します。完全な事前確認チェックリストについては、references/preflight.md を参照してください。

引き継ぎルール

シナリオ	引き継ぎ先
AppHost またはそのリソースの起動、停止、待機、再起動	aspire-orchestration スキル
実行中またはデプロイ済みのアプリのログ、トレース、メトリクス、ダッシュボード	aspire-monitoring スキル
AppHost の作成 — インテグレーションの追加、リソースの接続、環境の設定	aspireify スキル
デプロイ済みアプリの診断 — App Insights、ACA ログ、AKS Container Insights	azure-diagnostics スキル（azure-skills）

デプロイを azure-skills に引き継いではいけません。Aspire は AppHost モデルを通じて、Docker Compose／Kubernetes／Azure／AWS にわたる公開、デプロイ、破棄をエンドツーエンドで処理します。

プロジェクトローカルのスキルによるオーバーライド

.agents/skills/aspire-deployment/SKILL.md が存在する場合（aspire agent init によって配置されます）、このプラグインスキルよりもそちらを優先してください。これは、利用側の Aspire CLI に合わせてコンテンツのバージョンが調整された、プロジェクトローカルの正式なバージョンです。このプラグインスキルは、まだ aspire agent init を実行していないリポジトリ向けの常時有効なセーフティネットです。