Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Exécution et utilisation de microVMS

Cette section explique comment démarrer des microVM, se connecter à vos applications en cours d'exécution, gérer le cycle de vie des micromachines virtuelles et gérer le dimensionnement.

Démarrage d'une microVM

Utilisez la run-microvm commande pour lancer une nouvelle microVM à partir d'une image spécifiée. Lambda fournit les ressources nécessaires, crée un point de terminaison HTTPS dédié et démarre votre application à partir de la capture d'image.

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

Une microVM est créée lorsque vous appelezrun-microvm. Chaque microVM possède son propre point de terminaison dédié. Il n'y a pas d'équilibrage de charge entre les microVM à partir d'un seul point de terminaison : chaque point de terminaison est lié à une seule microVM.

Le seul paramètre obligatoire est --image-identifier (qui doit être l'ARN de l'image microVM). Tous les autres paramètres sont facultatifs.

Paramètres clés

Configuration de la politique d'inactivité

Lorsqu'elle est activée, la politique de ralenti contrôle la suspension et la reprise automatiques. La présence de trafic via le point de terminaison de la microVM indique une activité. Si aucun trafic n'arrive pendant la durée d'inactivité configurée, la microVM est considérée comme inactive et suspendue.

Charges utiles d'exécution

Le runHookPayload paramètre vous permet de transmettre les données de configuration par microVM (chaîne maximale de 16 Ko) lors de l'exécution. Lambda fournit cette charge utile dans le corps de la requête au hook du cycle de /run vie. Lambda injecte également le microvmId dans le corps de la requête.

Le /run hook reçoit un corps JSON avec la structure suivante :

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

Utilisez les charges utiles d'exécution pour fournir une configuration qui varie selon les microVM, par exemple, les identifiants de client, les jetons de session, les URL signées ou les chemins de Secrets Manager. Contrairement aux variables d'environnement (qui sont définies au niveau de l'image et partagées entre toutes les microVM à partir de cette image), la charge utile du run hook est unique à chaque 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'

Lorsque vous n'avez plus besoin d'une microVM, mettez-la hors service pour arrêter toute charge. Pour obtenir des instructions, veuillez consulter Mettre fin à une microVM.

Connexion à une microVM

Chaque microVM reçoit une URL de point de terminaison HTTPS publique unique, attribuée lorsque vous appelezrun-microvm. Vous vous connectez à votre application exécutée dans le microVM via cette URL.

Authentification

Toutes les demandes adressées à un point de terminaison microVM nécessitent un jeton d'authentification JWE. Il n'existe aucune option d'accès non authentifié. Générez un jeton avec create-microvm-auth-token :

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

Les jetons sont limités à des ports spécifiques et ont une date d'expiration configurable. Vous pouvez restreindre l'accès à un seul port, à une plage de ports ou à tous les ports :

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

Routage des ports

Par défaut, Lambda achemine le trafic entrant vers le port 8080 de votre microVM. Pour effectuer un routage vers un autre port, incluez l'X-aws-proxy-porten-tête dans votre demande. Le port cible doit être compris dans les limites allowedPorts définies dans le jeton d'authentification.

Protocoles

Lambda MicroVMS prend en charge le WebSockets gRPC et HTTP/2 le SSE sur l'URL du point de terminaison.

Pour les WebSocket connexions, transmettez le jeton d'authentification et le port cible via des sous-protocoles :

// 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 supprime les MicroVM-specific sous-protocoles de la demande avant de la transmettre à votre application.

Exemples de SDK

Les exemples suivants montrent comment exécuter une microVM et s'y connecter à l'aide des AWS SDK.

Python

Exemple Exemple — Exécution d'une microVM et connexion avec 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

Exemple Exemple — Exécution d'une microVM et connexion à AWS SDK pour 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());

Envoi de demandes

Bash

Exemple Exemple — Envoi d'une requête avec cURL

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

Python

Exemple Exemple — Envoi d'une demande avec la bibliothèque de requêtes

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

Node.js

Exemple Exemple — Envoi d'une demande avec fetch

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

Hooks de cycle de vie

Les Lifecycle Hooks vous permettent d'exécuter une logique personnalisée à des moments clés du cycle de vie d'une microVM : au démarrage, à la suspension, à la reprise ou à la fin du cycle de vie. Utilisez des hooks pour initialiser l'état par locataire, vider les données avant la suspension, actualiser les informations d'identification lors de la reprise ou nettoyer les ressources avant la résiliation.

Chaque hook est un point de terminaison HTTP exposé par votre application. Lambda envoie une requête POST au hook lors de l'événement de cycle de vie approprié. Les Hooks écoutent /aws/lambda-microvms/runtime/v1/<hook-name> le chemin du port que vous configurez.

Votre microVM commence à recevoir du trafic externe une fois que le /run hook a renvoyé le HTTP 200. D'ici là, le point de terminaison ne transmet pas les demandes à votre application.

Pour les hooks qui s'exécutent lors de la création de l'image (/readyet/validate), voirHooks de création d'images MicroVM.

Spécification 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" }
  ]
}

Suspension et reprise des microVM

Suspendez les microVM pour réduire les coûts tout en préservant l'état des applications. Pendant que vous courez, vous payez des frais de calcul. Pendant la suspension, vous ne payez que les frais de stockage des instantanés.

Comment suspendre

Il existe deux manières de suspendre une microVM :

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

Le crochet /suspend

Avant de procéder à la suspension, Lambda appelle /suspend votre hook. Utilisez-le pour vider les écritures en attente, fermer les connexions réseau et libérer des ressources qui ne doivent pas persister au-delà de la limite de suspension.

Comportement du CV

Lorsqu'une microVM redémarre (via un appel d'API ou une reprise automatique), Lambda restaure la mémoire et l'état du disque à partir du point de contrôle de suspension. La microVM reste en SUSPENDED état pendant l'exécution du /resume hook. Une fois que le hook a renvoyé le HTTP 200, la microVM passe au trafic RUNNING et commence à en recevoir.

Utilisez le /resume hook pour actualiser les informations d'identification, rétablir les connexions réseau et valider l'état.

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

Auto-resume

Lorsque autoResumeEnabled=true le trafic arrive au point de terminaison d'une microVM suspendue, Lambda reprend automatiquement la microVM. Lambda conserve la demande entrante pendant que le CV est terminé (y compris le /resume hook), puis la transmet à votre application.

Le CV ajoute de la latence à la première demande. La durée dépend de la taille de l'état suspendu restauré et de la durée de votre /resume crochet.

Si la reprise échoue, Lambda renvoie 502 Bad Gateway à l'appelant.

Mise à l'échelle et simultanéité

Vous créez de nouveaux microVM en appelant. run-microvm Chaque microVM possède son propre point de terminaison dédié. Il n'y a pas d'équilibrage de charge entre les microVM à partir d'un seul point de terminaison.

Account-level capacité — Votre compte dispose d'un quota pour la mémoire totale qui peut être allouée à toutes vos microVM dans l'SUSPENDEDÉtat RUNNING ou dans une région, et vous pouvez augmenter verticalement ce quota jusqu'à quatre fois. Pour demander une augmentation de quota, rendez-vous sur la console Service Quotas et recherchez Lambda MicroVM.

Modèle de coûts :

Stratégies de gestion des capacités :

Mettre fin à une microVM

Mettez fin à une microVM lorsqu'elle n'est plus nécessaire. La résiliation libère toutes les ressources informatiques et arrête tous les frais.

Avant de libérer des ressources, Lambda appelle votre /terminate hook. Utilisez-le pour vider les données en attente ou avertir les systèmes externes.

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

Répertorier les microVM

Répertoriez tous les microVM de votre compte, éventuellement filtrés par image :

aws lambda-microvms list-microvms

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

Gestion des erreurs

Erreurs d'exécution

Le tableau suivant répertorie les erreurs courantes renvoyées par l'run-microvmAPI :

Réessayer la stratégie

Pour les erreurs transitoires (ThrottlingException,InternalServerException), utilisez le recul exponentiel :

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