Ejecución y uso de MicroVM

En esta sección se describe cómo iniciar MicroVM, conectarse a las aplicaciones en ejecución, administrar el ciclo de vida de las MicroVM y gestionar el escalado.

Inicio de una MicroVM

Utilice el comando run-microvm para realizar el lanzamiento de una nueva MicroVM a partir de una imagen especificada. Lambda aprovisiona los recursos necesarios, crea un punto de conexión HTTPS dedicado e inicia la aplicación a partir de la instantánea de la imagen.

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

Se crea una MicroVM cuando se llama a run-microvm. Cada MicroVM tiene su propio punto de conexión dedicado. No hay equilibrio de carga entre las MicroVM desde un único punto de conexión; cada punto de conexión está vinculado a una sola MicroVM.

El único parámetro obligatorio es --image-identifier, que debe ser el ARN de la imagen de MicroVM. Todos los demás parámetros son opcionales.

Parámetros clave

Configuración de la política de inactividad

Cuando está habilitada, la política de inactividad controla la suspensión y la reanudación automáticas. La presencia de tráfico a través del punto de conexión de la MicroVM indica actividad. Si no se recibe tráfico durante el periodo de inactividad configurado, la MicroVM se considera inactiva y se suspende.

Cargas útiles del tiempo de ejecución

El parámetro runHookPayload permite pasar datos de configuración para cada MicroVM durante el tiempo de ejecución, con un máximo de 16 KB en una cadena. Lambda entrega esta carga útil como parte del cuerpo de la solicitud al enlace de ciclo de vida /run. Lambda también inserta microvmId en el cuerpo de la solicitud.

El enlace /run recibe un cuerpo JSON con la siguiente estructura:

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

Utilice cargas útiles del tiempo de ejecución para proporcionar una configuración que varíe en cada MicroVM, por ejemplo, ID de inquilinos, tokens de sesión, URL firmadas o rutas de Secrets Manager. A diferencia de las variables de entorno, que se configuran en el nivel de la imagen y se comparten entre todas las MicroVM creadas a partir de esta, la carga útil del enlace de ejecución es exclusiva de cada 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'

Cuando ya no necesite una MicroVM, termínela para dejar de incurrir en cargos. Para obtener instrucciones, consulte Terminación de una MicroVM.

Conexión a una MicroVM

A cada MicroVM se le asigna una URL de punto de conexión HTTPS público única cuando se llama a run-microvm. La conexión a la aplicación que se ejecuta dentro de la MicroVM se realiza mediante esta URL.

Autenticación

Todas las solicitudes a un punto de conexión de MicroVM requieren un token de autenticación JWE. No existe una opción de acceso sin autenticación. Genere un token mediante create-microvm-auth-token:

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

Los tokens se limitan a puertos específicos y su caducidad se puede configurar. Puede restringir el acceso a un solo puerto, a un intervalo de puertos o a todos los puertos:

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

Enrutamiento de puertos

De forma predeterminada, Lambda enruta el tráfico entrante al puerto 8080 de la MicroVM. Para enrutar el tráfico a otro puerto, incluya el encabezado X-aws-proxy-port en la solicitud. El puerto de destino se debe encontrar dentro de los allowedPorts definidos en el token de autenticación.

Protocolos

Las MicroVM de Lambda admiten HTTP/2, WebSockets, gRPC y SSE mediante la URL del punto de conexión.

Para las conexiones WebSocket, pase el token de autenticación y el puerto de destino mediante subprotocolos:

// 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 elimina de la solicitud los subprotocolos específicos de la MicroVM antes de enviarla a la aplicación.

Ejemplos de SDK

Los siguientes ejemplos muestran cómo ejecutar una MicroVM y conectarse a esta mediante los SDK de AWS.

Python

ejemplo Ejemplo: ejecución de una MicroVM y conexión mediante 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

ejemplo Ejemplo: ejecución de una MicroVM y conexión mediante el SDK de AWS para 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());

Envío de solicitudes

Bash

ejemplo Ejemplo: envío de una solicitud con cURL

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

Python

ejemplo Ejemplo: envío de una solicitud con la biblioteca de solicitudes

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

Node.js

ejemplo Ejemplo: envío de una solicitud con fetch

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

Enlaces de ciclo de vida

Los enlaces de ciclo de vida permiten ejecutar lógica personalizada en momentos clave del ciclo de vida de la MicroVM: cuando se inicia, se suspende, se reanuda o termina. Utilice los enlaces para inicializar el estado de cada inquilino, forzar la escritura de los datos pendientes antes de la suspensión, actualizar las credenciales tras la reanudación o liberar los recursos antes de la terminación.

Cada enlace es un punto de conexión HTTP que la aplicación expone. Lambda envía una solicitud POST al enlace cuando se produce el evento correspondiente del ciclo de vida. Los enlaces escuchan en la ruta /aws/lambda-microvms/runtime/v1/<hook-name> del puerto que configure.

La MicroVM comienza a recibir tráfico externo una vez que el enlace /run devuelve el código de estado HTTP 200. Hasta ese momento, el punto de conexión no reenvía las solicitudes a la aplicación.

Para consultar los enlaces que se ejecutan durante la creación de la imagen (/ready y /validate), consulte Enlaces de compilación de imágenes de MicroVM.

Especificación de 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" }
  ]
}

Suspensión y reanudación de MicroVM

La suspensión de las MicroVM permite reducir los costos y, al mismo tiempo, conservar el estado de la aplicación. Mientras están en ejecución, se aplican cargos por computación. Mientras están suspendidas, solo se aplican cargos por el almacenamiento de instantáneas.

Cómo suspender una MicroVM

Hay dos formas de suspender una MicroVM:

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

El enlace /suspend

Antes de suspender la MicroVM, Lambda llama al enlace /suspend. Utilícelo para completar las escrituras pendientes, cerrar las conexiones de red y liberar los recursos que no se deban conservar tras la suspensión.

Comportamiento de la reanudación

Cuando una MicroVM se reanuda, ya sea mediante una llamada a la API o mediante la reanudación automática, Lambda restaura el estado de la memoria y del disco a partir del punto de control de la suspensión. La MicroVM permanece en el estado SUSPENDED mientras se ejecuta el enlace /resume. Después de que el enlace devuelve una respuesta HTTP 200, la MicroVM pasa al estado RUNNING y comienza a recibir tráfico.

Utilice el enlace /resume para renovar las credenciales, restablecer las conexiones de red y validar el estado.

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

Reanudación automática

Si es autoResumeEnabled=true y llega tráfico al punto de conexión de una MicroVM suspendida, Lambda reanuda automáticamente la MicroVM. Lambda retiene la solicitud entrante hasta que finaliza la reanudación, incluida la ejecución del enlace /resume, y después la entrega a la aplicación.

La reanudación aumenta la latencia de la primera solicitud. La duración depende del tamaño del estado suspendido que se restaura y de la duración de la ejecución del enlace /resume.

Si la reanudación no se completa correctamente, Lambda devuelve al emisor de la llamada el error 502 (puerta de enlace incorrecta).

Escalado y simultaneidad

Las nuevas MicroVM se crean mediante una llamada a run-microvm. Cada MicroVM tiene su propio punto de conexión dedicado. No hay equilibrio de carga entre varias MicroVM mediante un único punto de conexión.

Capacidad en el nivel de la cuenta: la cuenta tiene una cuota para la memoria total que se puede asignar entre todas las MicroVM que se encuentren en el estado RUNNING o SUSPENDED en una región. Puede escalar verticalmente hasta cuatro veces el valor de esta cuota. Para solicitar un aumento de la cuota, acceda a la consola de Service Quotas y busque MicroVM de Lambda.

Modelo de costos:

Estrategias para administrar la capacidad:

Terminación de una MicroVM

Termine una MicroVM cuando ya no la necesite. La terminación libera todos los recursos de computación y hace que dejen de aplicarse todos los cargos.

Antes de liberar los recursos, Lambda llama al enlace /terminate. Utilícelo para completar la escritura de los datos pendientes o notificar a los sistemas externos.

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

Enumeración de MicroVM

Enumere todas las MicroVM de la cuenta, con la opción de filtrarlas por imagen:

aws lambda-microvms list-microvms

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

Gestión de errores

Errores de ejecución

En la siguiente tabla se indican los errores habituales que devuelve la API run-microvm:

Estrategia de reintento

Para los errores transitorios (ThrottlingException, InternalServerException), utilice el retroceso exponencial:

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