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별 구성 데이터(최대 16KB 문자열)를 전달할 수 있습니다. 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에 연결

모든 MicroVM은 run-microvm을 직접적으로 호출할 때 할당되는 고유한 퍼블릭 HTTPS 엔드포인트 URL을 가져옵니다. 이 URL을 통해 MicroVM 내에서 실행되는 애플리케이션에 연결합니다.

Authentication

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 MicroVM은 엔드포인트 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를 사용하여 MicroVM에 연결하는 방법을 보여줍니다.

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 실행 및 AWS SDK for JavaScript로 연결

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을 일시 중지하는 방법에는 두 가지가 있습니다.

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

/suspend 후크

일시 중지하기 전에 Lambda는 /suspend 후크를 직접적으로 호출합니다. 이를 사용하여 보류 중인 쓰기를 플러시하고, 네트워크 연결을 닫고, 일시 중지 경계를 넘어 지속되지 않아야 하는 리소스를 해제합니다.

동작 재개

API 직접 호출 또는 자동 재개를 통해 MicroVM이 재개되면 Lambda는 일시 중지된 체크포인트에서 메모리 및 디스크 상태를 복원합니다. MicroVM은 /resume 후크가 실행되는 동안 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 잘못된 게이트웨이를 반환합니다.

스케일링 및 동시성

run-microvm을 직접적으로 호출하여 새 MicroVM을 생성합니다. MicroVM마다 전용 엔드포인트가 있습니다. 단일 엔드포인트에서 MicroVM 간에 로드 밸런싱이 수행되지 않습니다.

계정 수준 용량 - 계정에는 특정 리전 내에서 RUNNING 또는 SUSPENDED 상태인 모든 MicroVM에 할당할 수 있는 총 메모리에 대한 할당량이 있으며, 이 할당량의 최대 4배까지 수직적 스케일링이 가능합니다. 할당량 증가를 요청하려면 Service Quotas 콘솔을 방문하여 Lambda MicroVM을 검색합니다.

비용 모델:

용량 관리 전략:

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