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

MicroVM は run-microvm を呼び出すときに作成されます。各 MicroVM には独自の専用エンドポイントがあります。単一のエンドポイントからの MicroVM 間の負荷分散はありません。各エンドポイントは 1 つの MicroVM にリンクされます。

唯一の必須パラメータは --image-identifier です (これは MicroVM イメージの ARN である必要があります)。その他のすべてのパラメータは省略可能です。

主要パラメータ

ECR ポリシーの設定

有効にすると、アイドルポリシーは自動一時停止と再開を制御します。MicroVM のエンドポイントを介したトラフィックが存在する場合は、アクティビティのシグナルが送信されます。設定されたアイドル期間内にトラフィックが到着しない場合、MicroVM はアイドルとして処理され、一時停止します。

ランタイムペイロード

runHookPayload パラメータを使用すると、MicroVM ごとの設定データ (最大 16 KB 文字列) を実行時に渡すことができます。Lambda は、このペイロードをリクエスト本文の一部として /run ライフサイクルフックに配信します。Lambda は、リクエスト本文への microvmId の挿入も行います。

/run フックは、次の構造を持つ JSON 本文を受け取ります。

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

ランタイムペイロードを使用して、テナント ID、セッショントークン、署名付き URL、Secrets Manager パスなど、MicroVM ごとに異なる設定を提供します。イメージレベルで設定され、そのイメージからすべての 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 は、run-microvm を呼び出すときに割り当てられる一意のパブリック HTTPS エンドポイント URL を取得します。この 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、WebSocket、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 の例

次の例は、AWS SDK を使用して MicroVM を実行して接続する方法を示しています。

Python

例例 – boto3 でMicroVM を実行して接続する

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

例例 – AWS SDK for JavaScript で MicroVM を実行して接続する

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());

ライフサイクルフック

ライフサイクルフックを使用すると、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 を一時停止する方法は 2 つあります。

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 を再開します。再開が完了する間 (/resumeフックを含む)、Lambda はインバウンドリクエストを保持し、それをアプリケーションに配信します。

再開すると最初のリクエストにレイテンシーが追加されます。期間は、復元される一時停止状態のサイズと /resume フックの期間に応じて異なります。

再開が成功しない場合、Lambda は発信元に 502 Bad Gateway を返します。

スケーリングと同時実行

新しい MicroVM を作成するには、run-microvm を呼び出します。各 MicroVM には独自の専用エンドポイントがあります。1 つのエンドポイントから複数の MicroVM 間への負荷分散は行われません。

アカウントレベルの容量 – アカウントには、1 つのリージョンの RUNNING 状態または SUSPENDED 状態のすべての MicroVM に割り当てることができる合計メモリのクォータがあり、このクォータの 4 倍まで垂直スケーリングを行うことができます。クォータの引き上げをリクエストするには、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")