MicroVM 실행 및 사용

MicroVM 실행 및 사용 (Running and using MicroVMs)

이 섹션은 MicroVM을 시작하고, 실행 중인 애플리케이션에 연결하며, MicroVM 수명주기를 관리하고, 확장을 처리하는 방법을 설명합니다.

출처: AWS Lambda 개발자 안내서

본문

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이어야 함). 다른 모든 파라미터는 선택 사항입니다.

주요 파라미터

파라미터	설명
`--image-identifier`	(필수) 실행할 MicroVM 이미지의 ARN.
`--image-version`	실행할 MicroVM 이미지의 버전. 기본값은 최신 활성 버전.
`--execution-role-arn`	MicroVM이 다른 AWS 서비스와 상호작용할 런타임 권한을 제공하는 IAM 역할.
`--idle-policy`	자동 일시 중단 및 재개 동작 제어. 다음 섹션의 유휴 정책 구성을 참조.
`--maximum-duration-in-seconds`	Lambda가 종료하기 전에 MicroVM이 실행 중 또는 일시 중단 상태로 남을 수 있는 최대 기간. 범위: 1–28,800초(8시간).
`--run-hook-payload`	MicroVM 시작 시 `/run` 수명주기 훅으로 전달되는 문자열 페이로드(최대 16KB).
`--logging`	로깅 구성. CloudWatch 로그 그룹과 스트림을 사용자 지정하거나 로깅을 완전히 비활성화.
`--ingress-network-connectors`	인바운드 HTTPS 연결을 활성화하는 인그레스 커넥터의 ARN.
`--egress-network-connectors`	아웃바운드 연결(인터넷 또는 VPC)용 이그레스 커넥터의 ARN.

참고

인그레스 연결을 비활성화하려면 Lambda 제공 NO_INGRESS 커넥터를 사용하세요. 네트워크 커넥터에 대한 자세한 내용은 네트워킹을 참조하세요.

유휴 정책 구성

활성화되면 유휴 정책은 자동 일시 중단과 재개를 제어합니다. MicroVM의 엔드포인트를 통한 트래픽의 존재는 활동 신호입니다. 구성된 유휴 시간 동안 트래픽이 도착하지 않으면 MicroVM은 유휴 상태로 간주되어 일시 중단됩니다.

필드	설명
`autoResumeEnabled`	`true`이면 MicroVM이 일시 중단 중에 엔드포인트로 트래픽이 도착할 때 자동으로 재개됨.
`maxIdleDurationSeconds`	트래픽 없이 보낸 후 MicroVM이 일시 중단되는 시간(초). 최대값: 28,800(8시간).
`suspendedDurationSeconds`	Lambda가 종료하기 전에 MicroVM이 일시 중단 상태로 남아 있는 시간(초).

참고

엔드포인트를 통해 트래픽을 능동적으로 보내거나 받지 않는 비동기 애플리케이션의 경우 자동 일시 중단을 비활성화하거나 적절한 유휴 시간을 구성하세요.

런타임 페이로드

runHookPayload 파라미터로 런타임에 MicroVM별 구성 데이터(최대 16KB 문자열)를 전달할 수 있습니다. Lambda는 이 페이로드를 /run 수명주기 훅에 대한 요청 본문의 일부로 전달합니다. Lambda는 또한 요청 본문에 microvmId를 주입합니다.

/run 훅은 다음 구조의 JSON 본문을 받습니다:

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

런타임 페이로드를 사용해 MicroVM마다 다른 구성(예: 테넌트 ID, 세션 토큰, 서명된 URL, Secrets Manager 경로)을 제공하세요. 환경 변수(이미지 수준에서 설정되어 해당 이미지의 모든 MicroVM 간에 공유됨)와 달리 run 훅 페이로드는 각 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.<token>",  // Auth token
  "lambda-microvms.port.9000"                     // Target port
];
const ws = new WebSocket('wss://<endpoint>/<path>', protocols);

Lambda는 요청을 애플리케이션으로 전달하기 전에 MicroVM 특정 하위 프로토콜을 제거합니다.

SDK 예제

다음 예제는 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://<endpoint>/<path>' \
  -H 'X-aws-proxy-auth: <token>' \
  -H 'X-aws-proxy-port: 8080'

Python:

예제 — requests 라이브러리로 요청 보내기:

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

Node.js:

예제 — fetch로 요청 보내기:

const response = await fetch('https://<endpoint>/<path>', {
  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/ 경로에서 수신합니다.

MicroVM은 /run 훅이 HTTP 200을 반환한 후에 외부 트래픽을 받기 시작합니다. 그때까지 엔드포인트는 요청을 애플리케이션으로 전달하지 않습니다.

훅	호출 시점	목적
`/aws/lambda-microvms/runtime/v1/run`	MicroVM이 스냅샷에서 시작한 후	테넌트별 상태 초기화, 고유 값 재설정, 상태 검사 수행. 이 훅이 반환된 후 트래픽 시작.
`/aws/lambda-microvms/runtime/v1/resume`	MicroVM이 일시 중단 상태에서 재개된 후	네트워크 연결 재설정, 자격 증명 새로 고침, 상태 검증. 이 훅이 실행되는 동안 MicroVM은 `SUSPENDED` 상태로 유지되며, 훅이 반환된 후 `RUNNING`으로 전환.
`/aws/lambda-microvms/runtime/v1/suspend`	MicroVM이 일시 중단되기 전	대기 중인 쓰기 플러시, 연결 종료, 리소스 해제.
`/aws/lambda-microvms/runtime/v1/terminate`	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을 일시 중단하는 방법은 두 가지가 있습니다:

유휴 정책(자동) — 유휴 정책에서 maxIdleDurationSeconds를 구성합니다. 해당 시간 동안 MicroVM 엔드포인트에 트래픽이 도착하지 않으면 Lambda가 MicroVM을 자동으로 일시 중단합니다.
API 호출(명시적) — suspend-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를 반환합니다.

참고

자동 재개는 일시 중단 후 첫 번째 요청에만 대기 시간을 추가합니다. MicroVM이 실행 중인 동안의 후속 요청은 영향을 받지 않습니다.

확장 및 동시성

run-microvm을 호출해 새 MicroVM을 만듭니다. 각 MicroVM에는 자체 전용 엔드포인트가 있습니다. 단일 엔드포인트에서 MicroVM 간의 로드 밸런싱은 없습니다.

계정 수준 용량 — 계정에는 한 리전에서 RUNNING 또는 SUSPENDED 상태인 모든 MicroVM에 걸쳐 할당할 수 있는 총 메모리에 대한 할당량이 있으며, 이 할당량의 4배까지 수직 확장할 수 있습니다. 할당량 증가를 요청하려면 Service Quotas 콘솔을 방문해 Lambda MicroVMs를 검색하세요.

비용 모델:

실행 중인 MicroVM은 컴퓨팅 요금이 부과됩니다.
일시 중단된 MicroVM은 스냅샷 저장 요금만 부과되며 컴퓨팅 요금은 없습니다.
종료된 MicroVM은 요금이 부과되지 않습니다.

용량 관리 전략:

유휴 MicroVM 일시 중단 — 트래픽을 받지 않는 MicroVM을 자동으로 일시 중단하도록 유휴 정책을 구성합니다.
더 이상 필요하지 않은 MicroVM 종료 — suspendedDurationSeconds를 사용해 최대 일시 중단 기간 후 자동 종료하거나 terminate-microvm을 명시적으로 호출합니다.
유휴 정책 적정화 — 트래픽 패턴에 따라 maxIdleDurationSeconds를 설정합니다. 더 짧은 유휴 시간은 용량을 더 빨리 확보합니다.

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가 반환하는 일반적인 오류를 나열합니다:

오류	원인	해결 방법
`ServiceQuotaExceededException`	계정이 동시 MicroVM에 대한 메모리 할당량에 도달함	유휴 MicroVM 종료 또는 할당량 증가 요청
`ResourceNotFoundException`	지정된 이미지가 없거나 `CREATED` 상태가 아님	이미지 식별자 확인 및 빌드 완료 확인
`ValidationException`	하나 이상의 요청 파라미터가 유효하지 않음	유휴 정책 값, 이미지 식별자 형식, 커넥터 ARN 확인
`ThrottlingException`	이 작업의 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")

Lambda Managed Instances와의 지원되는 서비스 통합에 대한 정보는 통합을 참조하세요.

더 알아보기 (Learn more)

Lambda MicroVMs 소개
MicroVM 네트워킹
MicroVM 이미지 빌드 훅