aws-lambda-microvms

AWS Lambda 微型虚拟机

建议使用 AWS MCP 服务进行沙箱化执行和审计日志记录。

AWS Lambda 微型虚拟机是无服务器计算环境，结合了 Firecracker 虚拟机隔离能力与类似容器的高效性。每个微型虚拟机：

• 将应用程序作为 Firecracker 微型虚拟机中的容器运行——你可以在本地复现该环境。
• 在微型虚拟机内部以 Amazon Linux 2023 作为基础操作系统。
• 从映像构建时捕获的内存 + 磁盘快照启动，因此运行时会跳过应用程序初始化。
• 拥有专用的 HTTPS 端点，该端点已终止 TLS，可使用身份验证令牌访问。
• 可以在保留状态的情况下暂停和恢复；最长运行 8 小时。

两种资源模型：

• MicrovmImage — 由 {S3 zip with Dockerfile} + baseImageArn 构建的版本化构件。每个版本都包含按架构／芯片组划分的 Build。
• Microvm — 从某个映像版本创建（RunMicrovm）的运行实例。

两种角色：

• buildRoleArn — 在映像构建期间使用（S3 读取、CloudWatch 日志，以及可选的 ECR）。
• executionRoleArn — 由运行中的微型虚拟机在运行时担任。

适用场景

选择 Lambda 微型虚拟机的情况

• 分析工作负载 — 用于数据处理、ETL 作业或查询执行的隔离计算，并提供强大的租户隔离。
• AI／Agent 代码执行沙箱 — 每个会话都使用全新、隔离的环境，并可在多轮交互之间快速恢复。
• 交互式代码练习场和笔记本 — 执行用户代码的 Jupyter、REPL 和开发环境。
• 强化学习环境 — 每个回合都使用干净的环境，并可访问工具。
• 多租户 CI 执行器／构建运行器 — 提供强大的租户隔离。
• 游戏／模拟服务器 — 有状态、长时间运行（最长 8 小时）的工作负载。
• 安全扫描 — 在隔离环境中运行不可信的分析器。

一般而言，Lambda 微型虚拟机适用于长时间运行的会话、真正监听端口的服务器（gRPC、WebSocket、自定义 TCP 协议）、需要在非活动期间保留状态（暂停／恢复）、需要容器级访问权限（FUSE、eBPF、自定义系统调用）的场景，或需要将会话路由到特定计算环境的场景。

选择 Lambda Event Functions 的情况

• 工作负载可在 15 分钟内完成。
• 按函数隔离已足够；如果普通事件／请求处理器需要使用专用于单个调用方或租户的执行环境，请在具有租户隔离模式的 On-Demand 上使用 Event Functions。不要假设 Lambda 会为每次调用创建全新的 Firecracker 虚拟机或执行环境。
• 交互之间无需在内存、磁盘或运行中的进程中保留会话状态。
• 更倾向于完全自动扩缩（无需管理 RunMicrovm）。
• 函数由事件源集成（S3、SQS、EventBridge 等）驱动。

选择其他方案的情况

• 需要持续计算超过 8 小时 → ECS／EKS／EC2。
• 需要修改内核或使用非 Linux 操作系统的直接迁移工作负载 → EC2。

典型工作流

0. 检查区域可用性 — 确认目标区域提供 Lambda MicroVMs（运行 aws lambda-microvms list-managed-microvm-images）。你的 S3 构件存储桶和任何网络连接器都必须与映像位于同一区域。
1. 打包应用：创建一个根目录中包含 Dockerfile 的 zip 文件，并上传到 S3（与映像位于同一区域）。
2. 实现生命周期钩子（可选，但建议实现）— 在你指定的端口（通常为 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 — 获取一个身份验证令牌（最长 60 分钟），并通过 allowedPorts 指定该令牌允许访问的端口。使用 X-aws-proxy-auth: <token> 向端点发送流量。
6. 挂起／恢复／终止 — 使用显式 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 参数分为两组：

microvmImageHooks（构建时）

建议： 实现映像构建钩子（/ready 和 /validate），以获得最佳性能。这些钩子可让平台捕获完整快照，并预取运行时会访问的部分内容。

钩子	用途	超时范围
ready	在应用启动期间调用。此钩子返回 200 状态码时，表示应用已准备好进行快照。请使用此钩子确保应用在拍摄快照前已完全启动。如果应用尚未准备就绪，请返回 503 状态码，直到它可以进行快照。	1–3600s（默认 30s）
validate	从 microVM 快照运行应用后调用。使用此钩子验证应用是否已准备好处理流量。此钩子还允许平台采样应用运行时会使用的快照部分，从而使 Lambda 能够预取这些部分，降低延迟。为获得最佳性能，请在 validate 期间向应用发送模拟负载。此钩子返回 200 时，表示 MicroVM 映像对 Lambda 有效。如果应用的 validate 工作流需要更多时间，请返回 503 状态码。	1–3600s（默认 30s）

为什么要实现 /ready？ 它会向平台表明应用已完全启动。如果没有此钩子，快照可能会在初始化过程中拍摄，导致缓存状态不完整，并使每次运行都重复部分启动流程。

为什么要实现 /validate？ 它可以让平台验证快照是否正确，并采样 RunMicrovm 期间会访问的快照部分。这样平台就能在后续启动时预取这些部分，从而缩短冷启动时间。

microvmHooks（运行时）

钩子	用途	超时范围
run	从快照启动后触发一次	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 / Support 提高。

其他功能

默认情况下，容器运行时使用一组受限的 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"]'

面向 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 会进入与正在运行的应用相同的容器——共享同一网络命名空间、文件系统和进程树。它通过基于 WebSocket 的 Shell 通道提供交互式 PTY，可从任何客户端（终端或浏览器）访问，适用于需要在 MicroVM 内执行命令的 Agent 驱动型工作流。

前提条件：MicroVM 必须在运行时附加 SHELL_INGRESS，调用方还需要 lambda:CreateMicrovmShellAuthToken。

已知限制

• 映像大小固定——无法从一个映像发布多种实例大小。请按每种大小准备一个映像。
• 映像版本会产生存储费用，即使没有任何 MicroVM 正在使用这些版本。请使用 delete-microvm-image-version 清理。
• **挂起 → 恢复时无法切换网络连接器。**LNC 在运行时绑定。
• **无法从 MicroVM 内部自行挂起。**请从外部（通过公共 API）调用 SuspendMicrovm。
• **身份验证令牌的 TTL 最长为 60 min。**对于长时间运行的客户端，请在过期前刷新。
• 运行时钩子（/run、/resume、/suspend、/terminate）仅用于快速通知（超时为 1–60s）。请勿将其用于耗时较长的初始化。

参考索引

选择与任务相符的参考文档：

• references/getting-started.md — 前提条件（S3 bucket、构建角色信任策略）、打包、端到端 CLI 操作指南、首次运行 + 令牌 + curl。
• references/lifecycle-model.md — 映像与 MicroVM 状态机、六个生命周期钩子（路径、超时、各钩子的操作）、空闲/挂起/恢复语义、钩子负载。
• references/snapshots-and-uniqueness.md — 快照包含的内容、唯一性陷阱、各语言的 CSPRNG、环境变量与运行配置、快照大小检查。
• references/networking.md — 入站与出站连接器、端口路由、X-aws-proxy-* 标头、WebSocket 子协议、HTTP/2 / gRPC、VPC 出站流量。
• references/iam-and-security.md — 构建角色与执行角色、信任策略、身份验证令牌（常规与 Shell）、lambda:PassNetworkConnector。
• references/troubleshooting.md — 映像构建错误代码、运行/连接失败、钩子超时、网络连接器问题、通过 Shell 访问进行调试。

参考资料中的约定

• 运行时侧的默认代理端口为 8080。可通过 X-aws-proxy-port 按请求覆盖，或通过子协议 lambda-microvms.port.<n> 按 WebSocket 覆盖。

安全注意事项

• 防止混淆代理问题——在信任策略中添加 aws:SourceAccount（或 aws:SourceArn）条件键。参见 references/iam-and-security.md。
• 快照唯一性——快照共享内存状态。恢复时重新播种 CSPRNG 并轮换密钥。参见 references/snapshots-and-uniqueness.md。
• 网络隔离——使用 VPC 出站连接器限制出站流量。
• 最小权限执行角色——将 IAM 策略范围限制到特定区域、账户和资源前缀。
• 日志记录——为 MicroVM 生命周期事件启用 CloudTrail。