运行和使用 MicroVM

本节介绍如何启动 MicroVM、连接到正在运行的应用程序、管理 MicroVM 生命周期和处理扩缩。

启动 MicroVM

使用 run-microvm 命令从指定的映像启动一个新的 MicroVM。Lambda 会预调配所需的资源，创建一个专用 HTTPS 端点，并从映像快照启动您的应用程序。

aws lambda-microvms run-microvm \
  --image-identifier arn:aws:lambda:us-east-1:123456789012:microvm-image:my-microvm-image \
  --ingress-network-connectors "arn:aws:lambda:us-east-1:aws:network-connector:aws-network-connector:ALL_INGRESS" \
  --egress-network-connectors "arn:aws:lambda:us-east-1:aws:network-connector:aws-network-connector:INTERNET_EGRESS" \
  --idle-policy '{"autoResumeEnabled":true,"maxIdleDurationSeconds":900,"suspendedDurationSeconds":1800}' \
  --maximum-duration-in-seconds 14400

在您调用 run-microvm 时将会创建一个 MicroVM。每个 MicroVM 都有自己的专用端点。来自单个端点的多个 MicroVM 之间不会执行负载均衡：每个端点都只会关联一个 MicroVM。

唯一必需的参数是 --image-identifier（且必须是 MicroVM 映像的 ARN）。所有其他参数都是可选的。

关键参数

空闲策略配置

空闲策略启用后，将会控制自动暂停和恢复行为。有流量通过 MicroVM 端点表示处于活动状态。如果在配置的空闲时间内没有流量到达，则 MicroVM 将被视为空闲并处于已暂停状态。

运行时有效载荷

您可以使用 runHookPayload 参数在运行时传递每个 MicroVM 的配置数据（最多 16 KB 字符串）。Lambda 会将此有效载荷作为请求正文的一部分传递给 /run 生命周期挂钩。Lambda 还会将 microvmId 注入到请求正文中。

/run 钩子会收到一个具有以下结构的 JSON 正文：

{
  "microvmId": "mvm-01234567-abcd-ef01-2345-6789abcdef01",
  "runHookPayload": "tenant-specific-string"
}

使用运行时有效载荷来提供因 MicroVM 而异的配置，例如租户 ID、会话令牌、签名 URL 或 Secrets Manager 路径。与环境变量（在映像级别设置并在该映像的所有 MicroVM 之间共享）不同，每个 MicroVM 的运行钩子有效载荷都是唯一的。

aws lambda-microvms run-microvm \
  --image-identifier arn:aws:lambda:us-east-1:123456789012:microvm-image:my-microvm-image \
  --run-hook-payload 'tenant-specific-string'

不再需要某个 MicroVM 时，请将其终止以停止产生所有收费。有关说明，请参阅终止 MicroVM。

连接到 MicroVM

每个 MicroVM 都会获得一个唯一的公共 HTTPS 端点 URL，这将在您调用 run-microvm 时分配。您可以通过此 URL 连接到在该 MicroVM 内运行的应用程序。

身份验证

对 MicroVM 端点的所有请求都需要 JWE 身份验证令牌。不提供未经身份验证进行访问的选项。使用 create-microvm-auth-token 生成令牌：

aws lambda-microvms create-microvm-auth-token \
  --microvm-identifier microvm-id \
  --expiration-in-minutes 30 \
  --allowed-ports '[{"allPorts":{}}]'

令牌的作用域仅限于特定的端口，并且具有可配置的过期时间。您可以将访问范围限定为单个端口、某个端口范围或所有端口：

{ "port": number }
{ "range": { "startPort": N, "endPort": N } }
{ "allPorts": {} }

端口路由

默认情况下，Lambda 会将入站流量路由到您的 MicroVM 内的 8080 端口。要路由到其他端口，请在请求中包含 X-aws-proxy-port 标头。目标端口必须位于身份验证令牌中定义的 allowedPorts 范围内。

协议

Lambda MicroVMs 支持通过端点 URL 的 HTTP/2、WebSockets、gRPC 和 SSE 访问。

对于 WebSocket 连接，请通过子协议传递身份验证令牌和目标端口：

// JavaScript WebSocket example
const protocols = [
  "lambda-microvms",                              // Required base protocol
  "lambda-microvms.authentication.<auth-token>",  // Auth token
  "lambda-microvms.port.9000"                     // Target port
];
const ws = new WebSocket('wss://<microvm-endpoint>/path', protocols);

在将请求转发到您的应用程序之前，Lambda 会从请求中移除特定于 MicroVM 的子协议。

SDK 示例

以下示例演示如何运行 MicroVM 并使用 AWS SDK 与之连接。

Python

例示例：运行 MicroVM 并使用 boto3 连接

import boto3, requests
client = boto3.client("lambda-microvms")
run_resp = client.run_microvm(
    imageIdentifier="arn:aws:lambda:us-east-1:123456789012:microvm-image:my-microvm-image",
    idlePolicy={"autoResumeEnabled": True, "maxIdleDurationSeconds": 900, "suspendedDurationSeconds": 300}
)
microvm_id = run_resp["microvmId"]
endpoint = run_resp["endpoint"]
print(f"MicroVM {microvm_id} running at {endpoint}")
token_resp = client.create_microvm_auth_token(
    microvmIdentifier=microvm_id, expirationInMinutes=30, allowedPorts=[{"allPorts": {}}]
)
token = token_resp["authToken"]["X-aws-proxy-auth"]
resp = requests.get(f"https://{endpoint}/health", headers={"X-aws-proxy-auth": token})
print(resp.status_code, resp.json())

Node.js

例示例：运行 MicroVM 并使用适用于 JavaScript 的 AWS SDK 连接

import { LambdaMicrovmsClient, RunMicrovmCommand, CreateMicrovmAuthTokenCommand } from "@aws-sdk/client-lambda-microvms";
const client = new LambdaMicrovmsClient({});
const { microvmId, endpoint } = await client.send(new RunMicrovmCommand({
  imageIdentifier: "arn:aws:lambda:us-east-1:123456789012:microvm-image:my-microvm-image",
  idlePolicy: { autoResumeEnabled: true, maxIdleDurationSeconds: 900, suspendedDurationSeconds: 300 }
}));
const { authToken } = await client.send(new CreateMicrovmAuthTokenCommand({
  microvmIdentifier: microvmId, expirationInMinutes: 30, allowedPorts: [{ allPorts: {} }]
}));
const resp = await fetch(`https://${endpoint}/health`, {
  headers: { "X-aws-proxy-auth": authToken["X-aws-proxy-auth"] }
});
console.log(await resp.json());

发送请求

Bash

例示例：发送带有 cURL 的请求

curl 'https://<microvm-endpoint>' \
  -H 'X-aws-proxy-auth: <TOKEN>' \
  -H 'X-aws-proxy-port: 8080'

Python

例示例：发送带有请求库的请求

import requests
response = requests.get('https://<microvm-endpoint>', headers={'X-aws-proxy-auth': '<TOKEN>'})
print(response.text)

Node.js

例示例：发送带有 fetch 的请求

const response = await fetch('https://<microvm-endpoint>', {
  headers: { 'X-aws-proxy-auth': '<TOKEN>', 'X-aws-proxy-port': '8080' }
});
console.log(await response.text());

生命周期钩子

通过使用生命周期挂钩，您可以在 MicroVM 生命周期中的关键时刻（启动、暂停、恢复或终止时）运行自定义逻辑。使用钩子初始化每个租户的状态，在暂停之前清空数据，在恢复时清空凭证，或者在终止之前清理资源。

每个钩子都是您的应用程序公开的一个 HTTP 端点。Lambda 将在相应的生命周期事件发生时向该钩子发送 POST 请求。钩子会在您配置的端口上侦听路径 /aws/lambda-microvms/runtime/v1/<hook-name>。

/run 钩子返回 HTTP 200 响应后，您的 MicroVM 会开始接收外部流量。在此之前，该端点不会将请求转发到您的应用程序。

有关在映像创建期间运行的钩子（/ready 和 /validate），请参阅 MicroVM 映像构建钩子。

OpenAPI 规范：

{
  "openapi": "3.0.2",
  "info": {
    "title": "Lambda MicroVMs Application Hook Interface",
    "version": "2025-12-03"
  },
  "paths": {
    "/ready": {
      "post": {
        "description": "Called by Lambda during MicroVM image creation to determine if the application has initialized.",
        "operationId": "Ready",
        "responses": {
          "200": { "description": "Successful invocation." },
          "503": { "description": "Application is not yet ready. Lambda retries until timeout." }
        }
      }
    },
    "/resume": {
      "post": {
        "description": "Called by Lambda when resuming a MicroVM that is in the SUSPENDED state.",
        "operationId": "Resume",
        "responses": {
          "200": { "description": "Successful invocation." }
        }
      }
    },
    "/run": {
      "post": {
        "description": "Called by Lambda when a new MicroVM is run from a MicroVM image.",
        "operationId": "Run",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RunRequestContent" }
            }
          }
        },
        "responses": {
          "200": { "description": "Successful invocation." }
        }
      }
    },
    "/suspend": {
      "post": {
        "description": "Called by Lambda when suspending a MicroVM.",
        "operationId": "Suspend",
        "responses": {
          "200": { "description": "Successful invocation." }
        }
      }
    },
    "/terminate": {
      "post": {
        "description": "Called by Lambda when terminating a MicroVM, before resources are released.",
        "operationId": "Terminate",
        "responses": {
          "200": { "description": "Successful invocation." }
        }
      }
    },
    "/validate": {
      "post": {
        "description": "Called by Lambda when running a MicroVM to validate the image build. Use this hook to perform tests that validate your application behaves correctly when running. Lambda also samples the portions of the image that are used when handling this request, allowing Lambda to prefetch those portions of the image to reduce latency at run time.",
        "operationId": "Validate",
        "responses": {
          "200": { "description": "Successful invocation." },
          "503": { "description": "Validation in progress. Lambda retries until timeout." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RunRequestContent": {
        "type": "object",
        "properties": {
          "microvmId": {
            "type": "string",
            "description": "The MicroVM identifier."
          },
          "runHookPayload": {
            "type": "string",
            "description": "Run hook payload provided to RunMicrovm."
          }
        }
      }
    }
  },
  "servers": [
    { "url": "/aws/lambda-microvms/runtime/v1" }
  ]
}

暂停和恢复 MicroVM

暂停 MicroVM 以降低成本，同时保持应用程序状态。运行期间，您需要支付计算费用。暂停后，您只需支付快照存储费用。

如何暂停

暂停 MicroVM 的方式有两种：

aws lambda-microvms suspend-microvm --microvm-identifier microvm-id

/suspend 钩子

在暂停之前，Lambda 会调用您的 /suspend 钩子。用来清空待处理的写入操作、关闭网络连接并释放不得跨越暂停边界持续存在的资源。

恢复行为

当 MicroVM 恢复时（通过 API 调用或自动恢复），Lambda 会从暂停检查点恢复内存和磁盘状态。/resume 钩子执行期间，MicroVM 会保持 SUSPENDED 状态。在钩子返回 HTTP 200 响应后，MicroVM 会变为 RUNNING 状态并开始接收流量。

使用 /resume 钩子刷新凭证、重新建立网络连接并验证状态。

aws lambda-microvms resume-microvm --microvm-identifier microvm-id

自动恢复

当autoResumeEnabled=true 并且有流量到达已暂停 MicroVM 的端点时，Lambda 会自动恢复该 MicroVM。Lambda 会在完成恢复过程中保留入站请求（包括 /resume 钩子），完成后才会将其传输给您的应用程序。

恢复操作会增加第一个请求的延迟。具体时长取决于要恢复的已暂停状态大小和 /resume 钩子的持续时间。

如果恢复未成功，Lambda 会向调用者返回 502 Bad Gateway 响应。

扩缩和并发

您可以通过调用 run-microvm 来创建新的 MicroVM。每个 MicroVM 都有自己的专用端点。无法在单个端点的 MicroVM 之间进行负载均衡。

账户级别容量：您的账户存在一个总内存配额，该配额可以分配给一个区域内所有处于 RUNNING 或 SUSPENDED 状态的所有 MicroVM，并且您可以垂直扩展到该配额的四倍。要请求增加配额，请访问 Service Quotas 控制台并搜索 Lambda MicroVMs。

成本模式：

容量管理策略：

终止 MicroVM

不再需要某个 MicroVM 时请将其终止。终止会释放所有计算资源并停止计算所有费用。

在释放资源之前，Lambda 会调用您的 /terminate 钩子。用来清空待处理的数据或通知外部系统。

aws lambda-microvms terminate-microvm --microvm-identifier microvm-id

列出 MicroVM

列出您账户中的所有 MicroVM，您可以选择按映像筛选：

aws lambda-microvms list-microvms

# Filter by image
aws lambda-microvms list-microvms --image-identifier my-image --image-version 1.0

错误处理

运行错误

下表列出了 run-microvm API 可能返回的常见错误：

重试策略

对于暂时性错误（ThrottlingException、InternalServerException），请使用指数回退：

import time, random
def run_with_retry(client, params, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.run_microvm(**params)
        except client.exceptions.ThrottlingException:
            delay = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)
    raise Exception("Max retries exceeded")