aws-lambda-microvms

AWS Lambda MicroVMs

建議使用 AWS MCP Server 進行沙盒執行與稽核日誌記錄。

AWS Lambda MicroVM 是一種無伺服器運算環境，結合了 Firecracker 虛擬機器（VM）的隔離性與類似容器的高效能。每台 MicroVM 具備以下特性：

• 將您的應用程式作為在 Firecracker MicroVM 內部的容器執行 — 您可以在本地端重現相同的環境。
• 在 MicroVM 內部使用 Amazon Linux 2023 作為基礎作業系統（Base OS）。
• 從映像檔建置時擷取的記憶體 ＋ 磁碟快照啟動，因此執行時會自動跳過應用程式的初始化階段。
• 擁有專屬且終止 TLS 驗證的 HTTPS 端點，可透過認證 Token 進行存取。
• 支援**暫停（Suspend）與恢復（Resume）**並保留執行狀態；最長存活時間可達 8 小時。

雙資源模型：

• MicrovmImage — 由 {包含 Dockerfile 的 S3 zip 檔} + baseImageArn 建置而成的版本化成品（Artifact）。每個版本皆針對不同晶片架構／處理器架構提供獨立的 Build。
• Microvm — 從指定映像檔版本建立並執行的實例（透過 RunMicrovm 建立）。

雙角色機制：

• buildRoleArn — 於映像檔建置期間使用（包含 S3 讀取、CloudWatch 日誌紀錄，以及可選的 ECR 權限）。
• executionRoleArn — 於執行階段由運行中的 MicroVM 所扮演（Assume）的角色。

適用場景

建議選擇 Lambda MicroVM 的時機

• 分析型工作負載 — 用於資料處理、ETL 作業或查詢執行的獨立運算環境，具備強效的租戶隔離能力。
• AI / Agent 程式碼執行沙盒 — 每個 Session 皆提供乾淨獨立的環境，且可在多輪對話之間快速恢復狀態。
• 互動式程式碼 Playground 與 Notebook — Jupyter、REPL 以及執行使用者程式碼的開發環境。
• 強化學習（Reinforcement Learning）環境 — 每個回合（Episode）皆具備乾淨環境，並支援工具存取。
• 多租戶 CI 執行器／Build Runner — 提供極高的租戶隔離度。
• 遊戲／模擬伺服器 — 具備 Session 狀態且需長時間執行（最長 8 小時）的工作負載。
• 安全性掃描 — 在隔離環境中執行不可信的分析工具。

整體而言，Lambda MicroVM 特別適合長效 Session、需要真實 Port 監聽的伺服器（gRPC、WebSocket、自訂 TCP 通訊協定）、閒置時保存狀態（暫停／恢復）、容器層級存取權限（FUSE、eBPF、自訂系統呼叫），或是需要將流量按 Session 親和性路由（Session-affine routing）至特定運算環境的場景。

建議選擇 AWS Lambda (Functions) 的時機

• 工作負載可在 15 分鐘內完成。
• 單次呼叫（Per-invocation）等級的隔離即可滿足需求，無須在記憶體中保留 Session 狀態。
• 偏好全自動彈性擴展（無須手動管理 RunMicrovm）。
• 由事件源整合（S3、SQS、EventBridge 等）直接觸發 Function。

建議選擇其他方案的時機

• 需要持續執行超過 8 小時的運算 → 請選擇 ECS / EKS / EC2。
• 需要修改 Linux 核心（Kernel）或非 Linux 作業系統的搬遷型（Lift-and-shift）工作負載 → 請選擇 EC2。

典型工作流程

0. 檢查區域可用性 — 確認目標 AWS 區域支援 Lambda MicroVM（可執行 aws lambda-microvms list-managed-microvm-images）。您的 S3 成品 Bucket 與所有網路連接器（Network Connector）必須與映像檔位於相同的區域。
1. 打包應用程式：將根目錄包含 Dockerfile 的檔案打包為 ZIP 格式並上傳至 S3（需與映像檔同區域）。
2. 實作生命週期 Hook（可選，但強烈建議）：在您指定的 Port 上（通常為 9000）提供 HTTP 端點，用於 /run、/resume、/suspend、/terminate、/ready 和 /validate。
3. CreateMicrovmImage — 指向 S3 成品、託管型基礎映像檔與建置角色。Lambda 會將 Dockerfile 編譯為 OCI 映像檔、啟動應用程式、呼叫 /ready、建立磁碟與記憶體快照，並可選擇透過 /validate 驗證。Lambda 會定期釋出新的託管映像檔版本，客戶應使用最新版本重新建置，以確保映像檔保持最新狀態。
4. RunMicrovm — 選擇映像檔版本、附加 executionRoleArn、設定 idlePolicy、進流量／出流量連接器，以及（可選）runHookPayload。完成後會取得 endpoint URL 與 microvmId。
5. CreateMicrovmAuthToken — 取得認證 Token（最長 60 分鐘），並透過 allowedPorts 指定該 Token 允許存取的 Port。發送流量至端點時需附帶 X-aws-proxy-auth: <token> Header。
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 (the bare name is rejected); --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 設定與生命週期 Hook）請參閱 references/getting-started.md。

Hook 設定規範

Hook 在 --hooks 參數下分為兩大部分：

microvmImageHooks（建置階段）

建議： 建議實作映像檔建置 Hook（/ready 與 /validate）以取得最佳效能。這能讓平台擷取完整的快照，並在執行時預取所需的資料區段。

Hook	用途	逾時範圍
ready	於應用程式啟動期間呼叫。當此 Hook 回傳 200 HTTP 狀態碼時，即向平台發送應用程式已就緒可進行快照的訊號。請利用此機制確保應用程式在擷取快照前已完整啟動。若應用程式尚未就緒，請回傳 503 狀態碼直到其就緒為止。	1–3600 秒（預設 30 秒）
validate	從 MicroVM 快照執行應用程式後呼叫。用於驗證應用程式已可正常處理流量。此外，此 Hook 能讓平台採樣應用程式執行時所存取的快照區段，以便 Lambda 事先預取（Prefetch）這些區段以降低延遲。欲獲得最佳效能，請在 validate 期間以模擬 Payload 測試應用程式。當此 Hook 回傳 200 時，代表向 Lambda 確認該 MicroVM 映像檔有效。若應用程式需要更多時間執行驗證流程，請回傳 503 狀態碼。	1–3600 秒（預設 30 秒）

為什麼要實作 /ready？ 它能向平台發送應用程式已完全啟動的訊號。若未實作，快照可能會在初始化途中被擷取，導致快取狀態不完整，進而在每次執行時都需要重複部分啟動程序。

為什麼要實作 /validate？ 它能讓平台驗證快照是否正確，並在執行 RunMicrovm 時採樣存取了哪些快照區段。如此一來，平台即可在日後啟動時**預取（Prefetch）**這些區段，大幅縮短冷啟動（Cold-start）時間。

microvmHooks（執行階段）

Hook	用途	逾時範圍
run	從快照啟動後觸發一次	1–60 秒（預設 1 秒）
resume	狀態由 SUSPENDED 轉為 RUNNING 後觸發	1–60 秒（預設 1 秒）
suspend	狀態由 RUNNING 轉為 SUSPENDED 前觸發	1–60 秒（預設 1 秒）
terminate	終止（Termination）前觸發	1–60 秒（預設 1 秒）

啟用所有 Hook 的完整範例，請參閱 references/getting-started.md。

單一 MicroVM 規格上限

資源	上限
每台 MicroVM 最大 vCPU 數	16
每台 MicroVM 最大記憶體	32 GB

關於所有其他配額 — 包括每個帳戶的併發 MicroVM 數、啟動速率、映像檔數量、最大執行時間、認證 Token TTL、Lambda 網路連接器（LNC）限制、單一 ENI 頻寬等 — 請參閱 AWS 官方文件或 Service Quotas 主控台。 大多數皆為軟性配額（Soft quota），可透過 Service Quotas 或聯繫 AWS 支援團隊申請提高上限。

附加 OS 權限（Capabilities）

預設情況下，容器僅具備有限的 Linux 權限（Capabilities）。僅在您的使用情境有特殊需求時，才需在建立映像檔時設定 --additional-os-capabilities '["ALL"]'：

• 檔案系統掛載 — EFS、基於 FUSE 的檔案系統。
• 巢狀容器（Nested containers） — 在 MicroVM 內部使用 containerd 執行其他容器。
• eBPF 程式 — 追蹤（Tracing）、效能分析（Profiling）或自訂網路策略。

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"]'

適用於 Agent 使用情境的 Shell 入口

若需要以程式化方式存取 Shell（適用於 Agent 工作流程、遠端命令執行），請使用 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"

Shell 將直接進入與運行中應用程式相同的容器內 — 共享相同的網路命名空間（Network namespace）、檔案系統與流程樹（Process tree）。這透過基於 WebSocket 的 Shell 通道提供了互動式 PTY，可從任何用戶端（終端機或瀏覽器）存取，非常適合需要在 MicroVM 內部執行命令的 Agent 驅動工作流程。

先決條件：MicroVM 執行時必須附加 SHELL_INGRESS，且呼叫者需具備 lambda:CreateMicrovmShellAuthToken 權限。

已知限制

• 映像檔為單一規格限制 — 無法...

<!-- truncated for translation batch; full body continues in source -->