aws-lambda-microvms

AWS Lambda MicroVMs

サンドボックスでの実行と監査ログには、AWS MCP サーバーを推奨します。

AWS Lambda MicroVMs は、Firecracker VM の分離性とコンテナのような効率性を兼ね備えたサーバーレスコンピューティング環境です。各 MicroVM は次のように動作します。

• アプリケーションを Firecracker microVM 内のコンテナとして実行します。環境をローカルで再現できます。
• MicroVM 内で、ベース OS として Amazon Linux 2023 を実行します。
• イメージのビルド時に取得した メモリとディスクのスナップショットから起動するため、実行時のアプリケーション初期化が不要です。
• 認証トークンでアクセスできる、TLS 終端済みの専用 HTTPS エンドポイントを備えます。
• 状態を保持したまま一時停止・再開できます。最長 8 時間動作します。

2 つのリソースモデル：

• MicrovmImage — {S3 zip with Dockerfile} + baseImageArn からビルドされるバージョン管理されたアーティファクトです。各バージョンには、アーキテクチャ／チップセットごとの Build があります。
• Microvm — イメージのバージョンから作成（RunMicrovm）される実行中のインスタンスです。

2 つのロール：

• buildRoleArn — イメージのビルド中に使用されます（S3 の読み取り、CloudWatch Logs、オプションの ECR）。
• executionRoleArn — 実行中の MicroVM によって、実行時に引き受けられます。

使用する場合

Lambda MicroVMs を選ぶ場合

• 分析ワークロード — データ処理、ETL ジョブ、クエリ実行向けの、テナント間の強力な分離を備えた隔離コンピューティング。
• AI／エージェントのコード実行サンドボックス — セッションごとに新しく隔離された環境を用意し、ターン間ですばやく再開できます。
• 対話型のコードプレイグラウンドとノートブック — Jupyter、REPL、ユーザーコードを実行する開発環境。
• 強化学習環境 — ツールアクセスを備えた、エピソードごとのクリーンな環境。
• マルチテナントの CI エグゼキューター／ビルドランナー — 強力なテナント分離。
• ゲーム／シミュレーションサーバー — セッション状態を保持する長時間（最長 8 時間）のワークロード。
• セキュリティスキャン — 信頼できないアナライザーを隔離環境で実行します。

一般に、Lambda MicroVMs は、長時間続くセッション、実際にポートをリッスンするサーバー（gRPC、WebSocket、カスタム TCP プロトコル）、非アクティブな期間をまたいで状態を保持する用途（一時停止／再開）、コンテナレベルのアクセス（FUSE、eBPF、カスタムシステムコール）、または特定のコンピューティング環境に固定されたセッションルーティングに適しています。

Lambda Event Functions を選ぶ場合

• ワークロードが 15 分以内に収まる場合。
• 関数単位の分離で十分な場合。通常のイベント／リクエストハンドラーにおいて、呼び出し元またはテナント専用の実行環境が必要な場合は、テナント分離モードでオンデマンドの Event Functions を使用してください。Lambda が呼び出しごとに新しい Firecracker VM または実行環境を作成すると想定しないでください。
• インタラクションの間、メモリ、ディスク、実行中のプロセスにセッション状態を保持する必要がない場合。
• （管理対象の RunMicrovm を使わずに）完全自動のスケーリングを優先する場合。
• イベントソース統合（S3、SQS、EventBridge など）によって関数が起動される場合。

別のサービスを選ぶ場合

• 8 時間を超える継続的なコンピューティング → ECS／EKS／EC2。
• カーネルの変更または Linux 以外の OS が必要なリフトアンドシフトのワークロード → EC2。

一般的なワークフロー

0. リージョンで利用可能か確認する — Lambda MicroVMs が対象のリージョンで利用可能であることを確認します（aws lambda-microvms list-managed-microvm-images を実行します）。S3 アーティファクトバケットとネットワークコネクターは、イメージと同じリージョンに配置する必要があります。
1. アプリをパッケージ化します。ルートに Dockerfile を含む zip を作成し、S3 にアップロードします（イメージと同じリージョン）。
2. ライフサイクルフックを実装する（任意ですが推奨） — 指定したポート（一般的には 9000）で、/run、/resume、/suspend、/terminate、/ready、/validate 用の HTTP エンドポイントを用意します。
3. CreateMicrovmImage — S3 アーティファクト、マネージドベースイメージ、ビルドロールを指定します。Lambda は Dockerfile を OCI イメージにコンパイルし、アプリを起動して /ready を呼び出し、ディスクとメモリのスナップショットを作成し、必要に応じて /validate で検証します。Lambda は定期的に新しいマネージドイメージバージョンをリリースします。最新のイメージを使用できるよう、ユーザーは最新バージョンを使って再ビルドする必要があります。
4. RunMicrovm — イメージバージョンを選択し、executionRoleArn をアタッチして、idlePolicy、イングレス／エグレスコネクター、および（任意で）runHookPayload を設定します。endpoint URL と microvmId が返されます。
5. CreateMicrovmAuthToken — トークンでアクセス可能なポートを指定する allowedPorts を設定して、認証トークン（最長 60 分）を取得します。X-aws-proxy-auth: <token> を指定して、エンドポイントにトラフィックを送信します。
6. Suspend / Resume / Terminate — API を明示的に呼び出すか、idlePolicy（maxIdleDurationSeconds、suspendedDurationSeconds、autoResumeEnabled）に処理を任せます。

主な CLI コマンド

# Create an image (zip with Dockerfile at root in S3, plus a managed base image)
aws lambda-microvms create-microvm-image \
  --name my-image \
  --base-image-arn arn:aws:lambda:<region>:aws:microvm-image:al2023-1 \
  --build-role-arn arn:aws:iam::<acct>:role/MicroVMBuildRole \
  --code-artifact '{"uri":"s3://<bucket>/<key>.zip"}'

# Run a MicroVM (returns endpoint + microvmId). --image-identifier takes the
# image ARN and --image-version is the full major.minor string.
aws lambda-microvms run-microvm \
  --image-identifier arn:aws:lambda:<region>:<acct>:microvm-image:my-image \
  --image-version 1.0 \
  --execution-role-arn arn:aws:iam::<acct>:role/MicroVMExecutionRole \
  --idle-policy '{"maxIdleDurationSeconds":900,"suspendedDurationSeconds":300,"autoResumeEnabled":true}'

# Mint an auth token and call the endpoint
TOKEN=$(aws lambda-microvms create-microvm-auth-token \
  --microvm-identifier microvm-... --expiration-in-minutes 30 \
  --allowed-ports '[{"port":8080}]' \
  --query 'authToken."X-aws-proxy-auth"' --output text)
curl "<endpoint>/" -H "X-aws-proxy-auth: $TOKEN"

# Lifecycle
aws lambda-microvms suspend-microvm   --microvm-identifier microvm-...
aws lambda-microvms resume-microvm    --microvm-identifier microvm-...
aws lambda-microvms terminate-microvm --microvm-identifier microvm-...

--hooks の設定やライフサイクルフックを含む手順全体については、references/getting-started.md を参照してください。

フックの設定

フックは --hooks パラメーターの下で、次の 2 つのグループに分けられています。

microvmImageHooks（ビルド時）

推奨： パフォーマンスを最大限に高めるには、イメージビルドフック（/ready と /validate）を実装してください。これにより、プラットフォームが完全なスナップショットを取得し、実行時にアクセスされる領域を事前取得できるようになります。

フック	目的	タイムアウト範囲
ready	アプリケーションの起動時に呼び出されます。このフックがステータスコード 200 を返すと、アプリケーションのスナップショットを作成できる状態になったことをプラットフォームに通知します。スナップショットの作成前にアプリケーションが完全に起動していることを確認するために使用します。アプリケーションがまだ準備できていない場合は、スナップショットを作成できる状態になるまでステータスコード 503 を返します。	1～3600 秒（デフォルト 30 秒）
validate	microVM スナップショットからアプリケーションを実行した後に呼び出されます。このフックを使用して、アプリケーションがトラフィックを処理できる状態か検証します。また、アプリケーションの実行時に使用されるスナップショットの領域をプラットフォームがサンプリングできるため、Lambda はその領域を事前取得してレイテンシーを低減できます。最適なパフォーマンスを得るには、検証中にモックペイロードをアプリケーションに送信してください。このフックが 200 を返すと、MicroVM イメージが有効であることを Lambda に通知します。検証ワークフローの実行にさらに時間が必要な場合は、ステータスコード 503 を返します。	1～3600 秒（デフォルト 30 秒）

/ready を実装する理由 アプリケーションの起動が完了したことをプラットフォームに通知できます。これがないと、初期化の途中でスナップショットが作成される可能性があり、キャッシュされた状態が不完全になるため、実行のたびに起動シーケンスの一部が繰り返されます。

/validate を実装する理由 プラットフォームがスナップショットの正しさを検証し、RunMicrovm 中にアクセスされるスナップショットの領域をサンプリングできるようになります。これにより、プラットフォームは次回以降の起動時にその領域を事前取得でき、コールドスタート時間を短縮できます。

microvmHooks（ランタイム）

フック	目的	タイムアウト範囲
run	スナップショットから実行した後に1回呼び出されます	1～60s（デフォルトは1s）
resume	SUSPENDED → RUNNING の後に呼び出されます	1～60s（デフォルトは1s）
suspend	RUNNING → SUSPENDED の前に呼び出されます	1～60s（デフォルトは1s）
terminate	終了前に呼び出されます	1～60s（デフォルトは1s）

すべてのフックを有効にする完全な例については、references/getting-started.md を参照してください。

MicroVM ごとのサイズ制限

リソース	上限
MicroVM あたりの最大 vCPU 数	16
MicroVM あたりの最大メモリ	32 GB

その他すべてのクォータ（アカウントあたりの同時実行 MicroVM 数、起動レート、イメージ数、最大実行時間、認証トークンの TTL、Lambda Network Connector（LNC）の制限、ENI あたりの帯域幅など）については、AWS のドキュメント／Service Quotas コンソールを確認してください。 その多くはソフトクォータで、Service Quotas／サポートを通じて引き上げられます。

その他の機能

デフォルトでは、コンテナは制限された Linux ケイパビリティのセットで実行されます。ユースケースで必要な場合に限り、イメージ作成時に --additional-os-capabilities '["ALL"]' を設定してください。

• ファイルシステムのマウント — EFS、FUSE ベースのファイルシステム。
• ネストされたコンテナ — MicroVM 内で containerd を使って追加のコンテナを実行します。
• eBPF プログラム — トレース、プロファイリング、カスタムネットワークポリシー。

aws lambda-microvms create-microvm-image \
  --name my-image \
  --base-image-arn arn:aws:lambda:<region>:aws:microvm-image:al2023-1 \
  --build-role-arn arn:aws:iam::<acct>:role/MicroVMBuildRole \
  --code-artifact '{"uri":"s3://<bucket>/<key>.zip"}' \
  --additional-os-capabilities '["ALL"]'

エージェントのユースケース向けシェル接続

プログラムからシェルにアクセスする場合（エージェントのワークフロー、リモートコマンド実行）は、SHELL_INGRESS ネットワークコネクターを使用します。

# 1. Run with SHELL_INGRESS enabled
aws lambda-microvms run-microvm \
  --image-identifier arn:aws:lambda:<region>:<acct>:microvm-image:my-image \
  --execution-role-arn arn:aws:iam::<acct>:role/MicroVMExecutionRole \
  --ingress-network-connectors '["arn:aws:lambda:<region>:aws:network-connector:aws-network-connector:SHELL_INGRESS"]' \
  --idle-policy '{"maxIdleDurationSeconds":900,"suspendedDurationSeconds":300,"autoResumeEnabled":true}'
# Response includes microvmId and endpoint

# 2. Mint a shell auth token (max 60 min; use shortest duration needed)
# Treat the token as a secret — avoid logging, storing in files, or shell history.
TOKEN=$(aws lambda-microvms create-microvm-shell-auth-token \
  --microvm-identifier microvm-... \
  --expiration-in-minutes 15 \
  --query 'authToken."X-aws-proxy-auth"' --output text)

# 3. Connect via WebSocket (port 8022)
# CLI args are visible in process listings (ps aux). For shared hosts,
# pipe the header via a file descriptor or use a wrapper script.
websocat "wss://<endpoint>/shell" \
  -H "Sec-WebSocket-Protocol: lambda-microvms.authentication.${TOKEN}, lambda-microvms, lambda-microvms.port.8022"

シェルは、実行中のアプリケーションと同じコンテナに接続されます。ネットワーク名前空間、ファイルシステム、プロセスツリーも同じです。これにより、任意のクライアント（ターミナルまたはブラウザー）からアクセスできる WebSocket ベースのシェルチャネルを介して、対話型 PTY を利用できます。MicroVM 内でコマンドを実行する必要がある、エージェント主導のワークフローに適しています。

前提条件：MicroVM は SHELL_INGRESS をアタッチして実行する必要があり、呼び出し元には lambda:CreateMicrovmShellAuthToken も必要です。

既知の制約

• イメージのサイズは1種類のみです — 1つのイメージから複数のインスタンスサイズを提供することはできません。サイズごとにイメージを用意してください。
• イメージのバージョンにはストレージコストが発生します。そのイメージで実行中の MicroVM がなくても同様です。delete-microvm-image-version を使用して削除してください。
• 一時停止から再開する際にネットワークコネクターを切り替えることはできません。 LNC は実行時に紐付けられます。
• MicroVM 内から自ら一時停止することはできません。 外部から（パブリック API を介して）SuspendMicrovm を呼び出してください。
• 認証トークンの最大 TTL は60分です。 長時間実行するクライアントでは、期限切れになる前に更新してください。
• ランタイムフック（/run、/resume、/suspend、/terminate）は高速な通知専用です（タイムアウトは1～60s）。時間のかかる初期化には使用しないでください。

リファレンス一覧

タスクに合ったリファレンスを選択してください。

• references/getting-started.md — 前提条件（S3 バケット、ビルドロールの信頼ポリシー）、パッケージ化、CLI を使ったエンドツーエンドの手順、初回実行＋トークン＋curl。
• references/lifecycle-model.md — イメージと MicroVM の状態遷移、6つのライフサイクルフック（パス、タイムアウト、各フックで行うこと）、アイドル／一時停止／再開のセマンティクス、フックのペイロード。
• references/snapshots-and-uniqueness.md — スナップショットの対象、一意性に関する落とし穴、言語ごとの CSPRNG、環境変数と実行設定の違い、スナップショットサイズの確認。
• references/networking.md — イングレスとエグレスのコネクター、ポートルーティング、X-aws-proxy-* ヘッダー、WebSocket サブプロトコル、HTTP/2／gRPC、VPC エグレス。
• references/iam-and-security.md — ビルドロールと実行ロール、信頼ポリシー、認証トークン（通常とシェル）、lambda:PassNetworkConnector。
• references/troubleshooting.md — イメージビルドのエラーコード、実行／接続の失敗、フックのタイムアウト、ネットワークコネクターの問題、シェルアクセスを使ったデバッグ。

リファレンスで使用する規則

• ランタイム側のデフォルトのプロキシポートは 8080 です。リクエストごとに X-aws-proxy-port を指定するか、WebSocket ごとにサブプロトコル lambda-microvms.port.<n> を指定して上書きできます。

セキュリティに関する考慮事項

• 混乱した代理人攻撃の防止 — 信頼ポリシーに aws:SourceAccount（または aws:SourceArn）条件キーを追加します。references/iam-and-security.md を参照してください。
• スナップショットの一意性 — スナップショットはメモリ状態を共有します。再開時に CSPRNG を再シードし、シークレットをローテーションしてください。references/snapshots-and-uniqueness.md を参照してください。
• ネットワークの分離 — VPC エグレスコネクターを使用して、アウトバウンドトラフィックを制限します。
• 最小権限の実行ロール — IAM ポリシーの適用範囲を、特定のリージョン、アカウント、リソースプレフィックスに限定します。
• ログ記録 — MicroVM のライフサイクルイベントについて、CloudTrail を有効にします。