本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

執行和使用 MicroVMs

本節說明如何啟動 MicroVMs、連線至執行中的應用程式、管理 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

當您呼叫 時，會建立 MicroVMrun-microvm。每個 MicroVM 都有自己的專用端點。從單一端點跨 MicroVMs 沒有負載平衡 – 每個端點都會連結到單一 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 不同的組態，例如租用戶 IDs、工作階段字符、已簽署 URLs 或 Secrets Manager 路徑。與環境變數 （在映像層級設定，並在該映像的所有 MicroVMs之間共用） 不同，執行勾點承載對於每個 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 特定的子通訊協定，然後再將其轉送到您的應用程式。

開發套件範例

下列範例示範如何執行 MicroVM 並使用 AWS SDKs 與其連線。

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

範例範例 – 使用擷取傳送請求

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

lifecycle hook

生命週期掛鉤可讓您在 MicroVM 生命週期中的關鍵點執行自訂邏輯，當它啟動、暫停、繼續或終止時。使用勾點初始化每個租用戶狀態、在暫停前排清資料、在繼續時重新整理登入資料，或在終止前清除資源。

每個勾點都是應用程式公開的 HTTP 端點。Lambda 會在適當的生命週期事件傳送 POST 請求至掛鉤。勾點會接聽您設定的連接埠/aws/lambda-microvms/runtime/v1/<hook-name>上的路徑。

您的 MicroVM 會在/run掛鉤傳回 HTTP 200 之後開始接收外部流量。在此之前，端點不會將請求轉送到您的應用程式。

如需在建立映像期間執行的勾點 (/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" }
  ]
}

暫停和繼續 MicroVMs

暫停 MicroVMs以降低成本，同時保留應用程式狀態。執行時，您需要支付運算費用。暫停時，您只需支付快照儲存費用。

如何暫停

有兩種方式可暫停 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 錯誤的閘道傳回給發起人。

擴展和並行

您可以透過呼叫 建立新的 MicroVMsrun-microvm。每個 MicroVM 都有自己的專用端點。從單一端點跨 MicroVMs沒有負載平衡。

帳戶層級容量 – 您的帳戶具有總記憶體的配額，可配置到區域中 RUNNING或 SUSPENDED 狀態的所有 MicroVMs，而且您可以垂直擴展到此配額的四倍。若要請求提高配額，請造訪 Service Quotas 主控台並搜尋 Lambda MicroVMs

成本模型：

管理容量的策略：

終止 MicroVM

不再需要 MicroVM 時將其終止。終止會釋出所有運算資源並停止所有費用。

在釋出資源之前，Lambda 會呼叫您的/terminate勾點。使用它來排清待處理的資料或通知外部系統。

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

列出 MicroVMs

列出您帳戶中的所有 MicroVMs，選擇性依影像篩選：

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")