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 décrit comment démarrer des micromachines virtuelles, vous connecter à vos applications en cours d'exécution, gérer le cycle de vie des micromachines virtuelles et gérer la mise à l'échelle.

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 l'instantané de l'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 micromachines virtuelles à partir d'un seul point de terminaison : chaque point de terminaison est lié à une seule micromachine virtuelle.

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 inactive

Lorsqu'elle est activée, la politique d'inactivité contrôle la suspension et la reprise automatiques. La présence de trafic via le terminal de la microVM signale 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

Avec runHookPayload ce paramètre, vous pouvez transmettre des données de configuration par microVM (chaîne de 16 Ko maximum) au moment de l'exécution. Lambda fournit cette charge utile dans le cadre du corps de la requête au hook du /run cycle de vie. Lambda injecte également le microvmId dans le corps de la requête.

Le /run hook reçoit un corps JSON dont la structure est la 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 en fonction de la microVM, par exemple, les identifiants de locataire, les jetons de session, les URL signées ou les chemins du 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 tous les frais. Pour obtenir des instructions, veuillez consulter Terminer une microVM.

Connexion à une microVM

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

Authentification

Toutes les demandes adressées à un terminal 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 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 acheminer vers un autre port, incluez l'X-aws-proxy-porten-tête dans votre demande. Le port cible doit se situer dans les limites allowedPorts définies dans le jeton d'authentification.

Protocoles

Lambda MicroVMS prend en charge HTTP/2 WebSockets, gRPC et 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 kits 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 avec 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 demande 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 requête 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 hooks de cycle de vie vous permettent d'exécuter une logique personnalisée à des moments clés du cycle de vie de la microVM : lors de son démarrage, de sa suspension, de sa reprise ou de son arrêt. Utilisez des hooks pour initialiser l'état par locataire, vider les données avant la suspension, actualiser les informations d'identification à 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 le chemin /aws/lambda-microvms/runtime/v1/<hook-name> du port que vous configurez.

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

Pour les hooks qui s'exécutent lors de la création de l'image (/readyet/validate), consultezHooks 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 micromachines virtuelles pour réduire les coûts tout en préservant l'état de l'application. 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 suspendre, Lambda appelle votre /suspend hook. Utilisez-le pour vider les écritures en attente, fermer les connexions réseau et libérer les ressources qui ne doivent pas persister au-delà de la limite de suspension.

Comportement du CV

Lorsqu'une microVM reprend (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é HTTP 200, la microVM passe au trafic RUNNING et commence à recevoir du trafic.

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 relance automatiquement la microVM. Lambda conserve la demande entrante pendant que le CV est terminé (y compris le /resume hook), puis la transmet à votre candidature.

Le CV ajoute de la latence à la première demande. La durée dépend de l'ampleur de l'état suspendu en cours de restauration et de la durée de votre /resume hameçon.

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

Mise à l'échelle et simultanéité

Vous créez de nouvelles micromachines virtuelles 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 micromachines virtuelles dans l'SUSPENDEDétat RUNNING ou d'une région, et vous pouvez le redimensionner verticalement jusqu'à quatre fois ce quota. Pour demander une augmentation de quota, accédez à la console Service Quotas et recherchez Lambda MicroVMS.

Modèle de coût :

Stratégies de gestion des capacités :

Terminer une microVM

Arrêtez une microVM lorsqu'elle n'est plus nécessaire. La résiliation libère toutes les ressources de calcul et met fin à tous les frais.

Avant de publier 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 toutes les micromachines virtuelles de votre compte, éventuellement filtrées 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 :

Stratégie de nouvelle tentative

Pour les erreurs transitoires (ThrottlingException,InternalServerException), utilisez une temporisation exponentielle :

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

Pour plus d'informations sur les intégrations de services prises en charge avec les instances gérées Lambda, consultez. Intégrations