Execução e uso de microVMs

Esta seção descreve como iniciar o microVMS, conectar-se aos aplicativos em execução, gerenciar o ciclo de vida da microVM e lidar com a escalabilidade.

Iniciar uma microVM

Use o comando run-microvm para iniciar uma nova microVM a partir de uma imagem especificada. O Lambda provisiona os recursos necessários, cria um endpoint HTTPS dedicado e inicia sua aplicação a partir do snapshot da imagem.

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

Uma microVM é criada quando você chama run-microvm. Cada microVM tem seu próprio endpoint dedicado. Não há balanceamento de carga entre microVMs a partir de um único endpoint, cada endpoint é vinculado a uma única microVM.

O único parâmetro necessário é --image-identifier (que deve ser o ARN da imagem da microVM). Todos os outros parâmetros são opcionais.

Principais parâmetros

Configuração da política de inatividade

Quando ativada, a política de inatividade controla a suspensão e a retomada automáticas. A presença de tráfego por meio do endpoint da microVM sinaliza a atividade. Se nenhum tráfego chegar durante o período de inatividade configurado, a microVM será tratada como ociosa e suspensa.

Cargas úteis de runtime

O parâmetro runHookPayload permite que você passe dados de configuração por microVM (sequência de caracteres de no máximo 16 KB) em runtime. O Lambda entrega essa carga útil como parte do corpo da solicitação ao gancho do ciclo de vida /run. O Lambda também injeta a microvmId no corpo da solicitação.

O hook /run recebe um corpo JSON com a seguinte estrutura:

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

Use cargas úteis de runtime para fornecer uma configuração que varie de acordo com a microVM, por exemplo, IDs de locatário, tokens de sessão, URLs assinados ou caminhos do Secrets Manager. Ao contrário das variáveis do ambiente (que são definidas na imagem e compartilhadas em todas as microVMs dessa imagem), a carga útil do hook de execução é exclusiva para 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'

Quando não precisar mais de uma microVM, encerre-a para interromper todas as cobranças. Para instruções, consulte Finalização de uma microVM.

Conexão a uma microVM

Cada microVM recebe um URL do endpoint HTTPS público exclusivo, atribuído quando você chama run-microvm. Você se conecta à aplicação em execução dentro da microVM por meio desse URL.

Autenticação

Todas as solicitações ao endpoint de uma microVM exigem um token de autenticação JWE. Não há opção de acesso não autenticado. Gere um token com create-microvm-auth-token:

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

Os tokens são destinados a portas específicas e têm uma expiração configurável. Você pode restringir o acesso a uma única porta, a um intervalo de portas ou a todas as portas:

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

Roteamento de portas

Por padrão, o Lambda roteia o tráfego de entrada para a porta 8080 em sua microVM. Para rotear para uma porta diferente, inclua o cabeçalho X-aws-proxy-port na sua solicitação. A porta de destino deve estar dentro das allowedPorts definidas no token de autenticação.

Protocolos

O Lambda MicroVMS oferece suporte a HTTP/2, WebSockets, gRPC e SSE no URL do endpoint.

Para conexões WebSocket, passe o token de autenticação e a porta de destino por meio de 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);

O Lambda remove os subprotocolos específicos da microVM da solicitação antes de encaminhá-la para sua aplicação.

Exemplos de SDK

Os exemplos a seguir mostram como executar uma microVM e se conectar a ela usando os AWS SDKs.

Python

exemplo Exemplo: execução de uma microVM e conexão com 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

exemplo Exemplo: execução de uma microVM e conexão com o AWS SDK 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());

Envio de solicitações

Bash

exemplo Exemplo: envio de uma solicitação com cURL

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

Python

exemplo Exemplo: envio de uma solicitação com a biblioteca de solicitações

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

Node.js

exemplo Exemplo: envio de uma solicitação com busca

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

Hooks do ciclo de vida

Os ganchos do ciclo de vida permitem que você execute lógica personalizada em pontos-chave do ciclo de vida da microVM: quando ela é iniciada, suspensa, retomada ou finalizada. Use hooks para inicializar o estado por locatário, liberar os dados antes da suspensão, atualizar as credenciais na retomada ou limpar os recursos antes da finalização.

Cada hook é um endpoint HTTP que sua aplicação expõe. O Lambda envia uma solicitação POST para o hook no evento de ciclo de vida apropriado. Os hooks recebem o caminho /aws/lambda-microvms/runtime/v1/<hook-name> na porta que você configura.

Sua microVM começa a receber tráfego externo depois que o hook /run retorna HTTP 200. Até esse ponto, o endpoint não encaminha solicitações para sua aplicação.

Para hooks executados durante a criação da imagem (/ready e /validate), consulte Hooks de compilação de imagens de microVM.

Especificação da 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" }
  ]
}

Suspensão e retomada de microVMs

Suspenda as microVMs para reduzir custos e, ao mesmo tempo, preservar o estado da aplicação. Durante a execução, você paga taxas de computação. Durante a suspensão, você paga somente as taxas de armazenamento de snapshots.

Como suspender

Há duas maneiras de suspender uma microVM:

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

O hook /suspend

Antes de suspender, o Lambda chama o hook /suspend. Use-o para liberar as gravações pendentes, encerrar as conexões de rede e liberar os recursos que não devem persistir além do limite de suspensão.

Retomar o comportamento

Quando uma microVM é retomada (por meio de uma chamada de API ou retomada automática), o Lambda restaura o estado da memória e do disco a partir do ponto de verificação da suspensão. A microVM permanece no estado SUSPENDED enquanto o hook /resume é executado. Depois que o hook retorna HTTP 200, a microVM faz a transição para RUNNING e começa a receber tráfego.

Use o hook /resume para atualizar as credenciais, restabelecer as conexões de rede e validar o estado.

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

Retomada automática

Quando autoResumeEnabled=true e o tráfego chega ao endpoint de uma microVM suspensa, o Lambda retoma a microVM automaticamente. O Lambda retém a solicitação de entrada enquanto a retomada é concluída (incluindo o hook /resume) e, em seguida, a entrega para sua aplicação.

A retomada adiciona latência à primeira solicitação. A duração depende do tamanho do estado suspenso que está sendo restaurado e da duração do seu hook /resume.

Se a retomada não for bem-sucedida, o Lambda retornará 502 Bad Gateway para o chamador.

Escalabilidade e simultaneidade

Você cria novas microVMs chamando run-microvm. Cada microVM tem seu próprio endpoint dedicado. Não há balanceamento de carga entre as microVMs a partir de um único endpoint.

Capacidade da conta: sua conta tem uma cota para a memória total que pode ser alocada em todas as suas microVMs no estado RUNNING ou SUSPENDED em uma região e você pode escalar verticalmente quatro vezes essa cota. Para solicitar um aumento na cota, acesse o console do Service Quotas e pesquise pelo Lambda MicroVMS.

Modelo de custo:

Estratégias para gerenciar a capacidade:

Finalização de uma microVM

Finalize uma microVM quando ela não for mais necessária. A finalização libera todos os recursos computacionais e interrompe todas as cobranças.

Antes de liberar os recursos, o Lambda chama o hook /terminate. Use-o para liberar os dados pendentes ou notificar sistemas externos.

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

Listar microVMs

Liste todas as microVMs em sua conta, filtrados opcionalmente por imagem:

aws lambda-microvms list-microvms

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

Tratamento de erros

Erros de execução

A tabela a seguir relaciona os erros comuns retornados pela API run-microvm:

Estratégia de repetição

Para erros transitórios (ThrottlingException, InternalServerException), use o recuo 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")