Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Esecuzione e utilizzo di MicroVMS

Questa sezione descrive come avviare MicroVMS, connettersi alle applicazioni in esecuzione, gestire il ciclo di vita MicroVM e gestire la scalabilità.

Avvio di una microVM

Utilizzare il run-microvm comando per avviare una nuova MicroVM da un'immagine specificata. Lambda fornisce le risorse necessarie, crea un endpoint HTTPS dedicato e avvia l'applicazione dall'istantanea dell'immagine.

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

Quando si effettua una chiamata, viene creata una microVM. run-microvm Ogni microVM ha il proprio endpoint dedicato. Non è previsto il bilanciamento del carico tra le microVM da un singolo endpoint: ogni endpoint è collegato a una singola microVM.

L'unico parametro richiesto è --image-identifier (che deve essere l'ARN dell'immagine MicroVM). Tutti gli altri parametri sono facoltativi.

Parametri chiave

Configurazione delle politiche di inattività

Se abilitata, la politica di inattività controlla la sospensione e la ripresa automatiche. La presenza di traffico attraverso l'endpoint della MicroVM segnala l'attività. Se non arriva traffico per la durata di inattività configurata, la microVM viene considerata inattiva e sospesa.

Payload di runtime

Il runHookPayload parametro consente di passare dati di configurazione per microVM (stringa massima 16 KB) in fase di esecuzione. Lambda fornisce questo payload come parte del corpo della richiesta al lifecycle hook. /run Lambda inserisce anche il microvmId nel corpo della richiesta.

L'/runhook riceve un corpo JSON con la seguente struttura:

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

Utilizza i payload di runtime per fornire una configurazione che varia in base alla microVM, ad esempio ID tenant, token di sessione, URL firmati o percorsi Secrets Manager. A differenza delle variabili di ambiente (che sono impostate a livello di immagine e condivise tra tutte le microVM di quell'immagine), il payload run hook è unico per ogni 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 non hai più bisogno di una microVM, interrompila per bloccare tutti gli addebiti. Per istruzioni, consulta Terminazione di una microVM.

Connessione a una microVM

Ogni microVM riceve un URL di endpoint HTTPS pubblico univoco, assegnato quando si effettua una chiamata. run-microvm Ti connetti alla tua applicazione in esecuzione all'interno della microVM tramite questo URL.

Autenticazione

Tutte le richieste a un endpoint MicroVM richiedono un token di autenticazione JWE. Non esiste un'opzione di accesso non autenticato. Genera un token con: create-microvm-auth-token

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

I token sono limitati a porte specifiche e hanno una scadenza configurabile. Puoi limitare l'accesso a una singola porta, a un intervallo di porte o a tutte le porte:

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

Routing delle porte

Per impostazione predefinita, Lambda indirizza il traffico in entrata alla porta 8080 all'interno della tua microVM. Per indirizzare verso una porta diversa, includi l'intestazione nella X-aws-proxy-port richiesta. La porta di destinazione deve rientrare nei valori allowedPorts definiti nel token di autenticazione.

Protocolli

Lambda MicroVMS supporta WebSockets gRPC e SSE sull'URL dell'endpoint. HTTP/2

Per le WebSocket connessioni, passa il token di autenticazione e la porta di destinazione tramite sottoprotocolli:

// 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 rimuove i MicroVM-specific sottoprotocolli dalla richiesta prima di inoltrarla all'applicazione.

Esempi SDK

Gli esempi seguenti mostrano come eseguire una microVM e connettersi ad essa utilizzando gli SDK. AWS

Python

Esempio Esempio: esecuzione di una microVM e connessione con 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

Esempio Esempio: esecuzione di una microVM e connessione con AWS SDK per 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());

Invio di richieste

Bash

Esempio Esempio — Invio di una richiesta con cURL

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

Python

Esempio Esempio: invio di una richiesta con la libreria delle richieste

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

Node.js

Esempio Esempio: invio di una richiesta 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());

Hook del ciclo di vita

I Lifecycle Hook consentono di eseguire la logica personalizzata nei punti chiave del ciclo di vita della microVM, ovvero all'avvio, alla sospensione, alla ripresa o all'interruzione. Usa gli hook per inizializzare lo stato di ogni tenant, cancellare i dati prima della sospensione, aggiornare le credenziali al ripristino o ripulire le risorse prima della chiusura.

Ogni hook è un endpoint HTTP esposto dall'applicazione. Lambda invia una richiesta POST all'hook all'evento del ciclo di vita appropriato. Gli hook ascoltano il percorso /aws/lambda-microvms/runtime/v1/<hook-name> sulla porta configurata.

La tua microVM inizia a ricevere traffico esterno dopo che l'/runhook ha restituito HTTP 200. Fino ad allora, l'endpoint non inoltrerà richieste all'applicazione.

Per gli hook che vengono eseguiti durante la creazione dell'immagine (/readyand/validate), vedi. Hook per la creazione di immagini MicroVM

Specifiche 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" }
  ]
}

Sospensione e ripresa di MicroVMS

Sospendi MicroVMS per ridurre i costi preservando allo stesso tempo lo stato dell'applicazione. Durante l'esecuzione, paghi i costi di elaborazione. Durante la sospensione, paghi solo i costi di archiviazione delle istantanee.

Come sospendere

Esistono due modi per sospendere una microVM:

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

L'hook /suspend

Prima della sospensione, Lambda chiama /suspend il tuo hook. Usalo per cancellare le scritture in sospeso, chiudere le connessioni di rete e rilasciare risorse che non devono persistere oltre il limite di sospensione.

Riprendi il comportamento

Quando una MicroVM si riattiva (tramite una chiamata API o una ripresa automatica), Lambda ripristina la memoria e lo stato del disco dal checkpoint di sospensione. La microVM rimane in stato durante l'esecuzione dell'hook. SUSPENDED /resume Dopo che l'hook restituisce HTTP 200, la microVM passa a e inizia a ricevere traffico. RUNNING

Usa l'/resumehook per aggiornare le credenziali, ristabilire le connessioni di rete e convalidare lo stato.

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

Auto-resume

Quando autoResumeEnabled=true il traffico arriva a un endpoint di MicroVM sospeso, Lambda riattiva automaticamente la MicroVM. Lambda conserva la richiesta in entrata durante il completamento del curriculum (incluso l'/resumehook), quindi la invia all'applicazione.

Il curriculum aggiunge latenza alla prima richiesta. La durata dipende dalla dimensione dello stato di sospensione da ripristinare e dalla durata dell'hook. /resume

Se la ripresa non riesce, Lambda restituisce 502 Bad Gateway al chiamante.

Scalabilità e concorrenza

È possibile creare nuove microVM chiamando. run-microvm Ogni microVM ha il proprio endpoint dedicato. Non è previsto il bilanciamento del carico tra le microVM da un singolo endpoint.

Account-level capacità: l'account dispone di una quota per la memoria totale che può essere allocata su tutte le microVM presenti in una regione RUNNING o SUSPENDED nello stato di una regione ed è possibile scalare verticalmente fino a quattro volte tale quota. Per richiedere un aumento della quota, visita la console Service Quotas e cerca Lambda MicroVMS.

Modello di costo:

Strategie per la gestione della capacità:

Terminazione di una microVM

Termina una microVM quando non è più necessaria. La terminazione sblocca tutte le risorse di elaborazione e interrompe tutti gli addebiti.

Prima di rilasciare le risorse, Lambda chiama /terminate il tuo hook. Usalo per cancellare i dati in sospeso o notificare sistemi esterni.

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

Elenco di microVMS

Elenca tutte le microVM presenti nel tuo account, filtrate facoltativamente per immagine:

aws lambda-microvms list-microvms

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

Gestione degli errori

Errori di esecuzione

La tabella seguente elenca gli errori più comuni restituiti dall'run-microvmAPI:

Riprova la strategia

Per gli errori transitori (ThrottlingException,InternalServerException), usa il backoff esponenziale:

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