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 di MicroVM e gestire la scalabilità.

Avvio di una MicroVM

Usa il run-microvm comando per avviare una nuova MicroVM da un'immagine specificata. Lambda fornisce le risorse richieste, 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 chiama, viene creata una MicroVM. run-microvm Ogni MicroVM ha il proprio endpoint dedicato. Non esiste un 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 dei criteri 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 in fase di esecuzione

Con il runHookPayload parametro, è possibile passare i dati di configurazione per microVM (stringa massima di 16 KB) in fase di esecuzione. Lambda invia questo payload come parte del corpo della richiesta al lifecycle hook. /run Lambda lo inserisce anche nel corpo della richiesta. microvmId

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 a seconda della microVM, ad esempio ID tenant, token di sessione, URL firmati o percorsi di Secrets Manager. A differenza delle variabili di ambiente (che sono impostate a livello di immagine e condivise tra tutte le microVM presenti nell'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, chiudila per interrompere 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 al momento della 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 è disponibile alcuna 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 assegnati 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 microVM. Per indirizzare verso una porta diversa, includi l'intestazione nella X-aws-proxy-port richiesta. La porta di destinazione deve rientrare in quella allowedPorts definita nel token di autenticazione.

Protocolli

Lambda MicroVMS supporta HTTP/2 WebSockets, gRPC e SSE tramite l'URL dell'endpoint.

Per le WebSocket connessioni, passa il token di autenticazione e la porta di destinazione tramite i 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 di 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

Gli hook del ciclo di vita consentono di eseguire una logica personalizzata nei punti chiave del ciclo di vita di MicroVM, quando viene avviato, sospeso, ripreso o terminato. Usa gli hook per inizializzare lo stato per tenant, cancellare i dati prima della sospensione, aggiornare le credenziali al momento della ripresa o ripulire le risorse prima della cessazione.

Ogni hook è un endpoint HTTP esposto dall'applicazione. Lambda invia una richiesta POST all'hook in corrispondenza dell'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 inoltra le richieste all'applicazione.

Per gli hook che vengono eseguiti durante la creazione dell'immagine (/readye/validate), consulta. ganci 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 ripristino di MicroVM

Sospendi MicroVMS per ridurre i costi preservando lo stato dell'applicazione. Durante l'esecuzione, paghi i costi di elaborazione. In caso di 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 di sospendere, Lambda chiama il tuo hook. /suspend Usalo per eliminare 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 riprende (tramite una chiamata API o un ripristino automatico), Lambda ripristina la memoria e lo stato del disco dal checkpoint di sospensione. La microVM rimane nello SUSPENDED stato durante l'esecuzione dell'/resumehook. Dopo che l'hook restituisce HTTP 200, la microVM passa 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 il autoResumeEnabled=true traffico arriva all'endpoint di una microVM sospesa, Lambda riprende la microVM automaticamente. Lambda trattiene la richiesta in entrata durante il completamento del curriculum (incluso l'hook), quindi la invia all'applicazione. /resume

Il curriculum aggiunge latenza alla prima richiesta. La durata dipende dalla dimensione dello stato sospeso da ripristinare e dalla durata dell'/resumehook.

Se la ripresa non ha esito positivo, Lambda restituisce 502 Bad Gateway al chiamante.

Scalabilità e concorrenza

È possibile creare nuove MicroVMS 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à: il tuo account ha una quota per la memoria totale che può essere allocata su tutte le tue MicroVM in SUSPENDED uno stato RUNNING o in una regione e puoi scalare verticalmente fino a quattro volte questa 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

Terminare una microVM quando non è più necessaria. La terminazione libera tutte le risorse di calcolo e interrompe tutti gli addebiti.

Prima di rilasciare risorse, Lambda richiama l'utente. /terminate Usalo per cancellare i dati in sospeso o inviare notifiche a sistemi esterni.

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

Elenco delle microVMS

Elenca tutti i MicroVM presenti nel tuo account, opzionalmente filtrati 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")

Per informazioni sulle integrazioni di servizi supportate con Lambda Managed Instances, consulta. Integrazioni