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 appelez`run-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 | Paramètre | Description | | --- | --- | | --image-identifier | (Obligatoire) L'ARN de l'image microVM à exécuter. | | --image-version | Version de l'image microVM à exécuter. Par défaut, il s'agit de la dernière version active. | | --execution-role-arn | Le rôle IAM qui fournit des autorisations d'exécution permettant à la microVM d'interagir avec d'autres AWS services. | | --idle-policy | Contrôle le comportement de suspension et de reprise automatiques. Consultez la section suivante sur la configuration de la politique d'inactivité. | | --maximum-duration-in-seconds | Durée maximale pendant laquelle la microVM peut rester en état de fonctionnement ou suspendu avant que Lambda ne l'arrête. Durée : 1 à 28 800 secondes (8 heures). | | --run-hook-payload | Une charge utile de chaîne (16 Ko maximum) envoyée au hook du /run cycle de vie au démarrage de la microVM. | | --logging | Configuration de la journalisation. Personnalisez le groupe de CloudWatch journaux et le flux, ou désactivez complètement la journalisation. | | --ingress-network-connectors | Le ou les ARN des connecteurs d'entrée qui permettent la connectivité HTTPS entrante. | | --egress-network-connectors | Le ou les ARN des connecteurs de sortie pour la connectivité sortante (Internet ou VPC). | **Note** Pour désactiver la connectivité d'entrée, utilisez le Lambda-provided `NO_INGRESS` connecteur. Pour plus de détails sur les connecteurs réseau, consultez[Réseaux](microvms-networking.md). ### 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. | Champ | Description | | --- | --- | | autoResumeEnabled | Lorsquetrue, la microVM reprend automatiquement lorsque le trafic arrive à son point de terminaison alors qu'il est suspendu. | | maxIdleDurationSeconds | Le nombre de secondes sans trafic après lesquelles la microVM est suspendue. Maximum : 28 800 (8 heures). | | suspendedDurationSeconds | Le nombre de secondes pendant lesquelles une microVM reste en état suspendu avant que Lambda ne l'arrête. | **Note** Pour les applications asynchrones qui n'envoient ou ne reçoivent pas activement de trafic via le terminal, désactivez la suspension automatique ou configurez une durée d'inactivité appropriée. ### 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](#microvms-launching-terminate). ## Connexion à une microVM Chaque microVM reçoit une URL de point de terminaison HTTPS public unique, attribuée lorsque vous appelez`run-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-port`en-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 ] **Example 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 ] **Example 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 ] **Example Exemple — Envoi d'une demande avec cURL** ``` curl 'https://<{{microvm-endpoint}}>' \ -H 'X-aws-proxy-auth: <{{TOKEN}}>' \ -H 'X-aws-proxy-port: 8080' ``` ------ #### [ Python ] **Example 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 ] **Example 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/` 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. | Crochet | Lorsqu'il est invoqué | Objectif | | --- | --- | --- | | /aws/lambda-microvms/runtime/v1/run | Après le démarrage de MicroVM à partir d'un instantané | Initialisez l'état par locataire, réinitialisez les valeurs uniques, effectuez des contrôles de santé. Le trafic commence après le retour de ce hook. | | /aws/lambda-microvms/runtime/v1/resume | Après la reprise de l'état suspendu de MicroVM | Re-establish connexions réseau, actualisation des informations d'identification, validation de l'état. La microVM reste en SUSPENDED état pendant l'exécution de ce hook ; elle passe RUNNING après le retour du hook. | | /aws/lambda-microvms/runtime/v1/suspend | Avant la suspension de MicroVM | Videz les écritures en attente, fermez les connexions, libérez des ressources. | | /aws/lambda-microvms/runtime/v1/terminate | Avant l'arrêt de MicroVM | Videz les données, notifiez les systèmes externes, nettoyez. | Pour les hooks qui s'exécutent lors de la création de l'image (`/ready`et`/validate`), consultez[Hooks de création d'images MicroVM](microvms-images.md#microvms-images-build-hooks). **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 : 1. **Politique d'inactivité (automatique) ** — Configurez `maxIdleDurationSeconds` dans la politique d'inactivité. Si aucun trafic n'arrive au point de terminaison de la microVM pendant cette durée, Lambda suspend automatiquement la microVM. 1. **Appel d'API (explicite) ** — Appel `suspend-microvm` à suspendre immédiatement : ``` 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. **Note** Auto-resume ajoute de la latence uniquement à la première demande après la suspension. Les requêtes suivantes pendant l'exécution de la microVM ne sont pas affectées. ## 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 : ** + L'exécution de microVM entraîne des frais de calcul. + Les micromachines virtuelles suspendues entraînent des frais de stockage des snapshots, mais pas des frais de calcul. + Les micromachines virtuelles résiliées n'entraînent aucun frais. **Stratégies de gestion des capacités : ** + **Suspendre les micromachines virtuelles inactives ** : configurez des politiques d'inactivité pour suspendre automatiquement les micromachines virtuelles qui ne reçoivent pas de trafic. + **Mettre fin aux micromachines virtuelles qui ne sont plus nécessaires ** : utilisez cette option `suspendedDurationSeconds` pour terminer automatiquement après une durée de suspension maximale, ou appelez explicitement. `terminate-microvm` + **Right-size politiques d'inactivité ** : définissez `maxIdleDurationSeconds` en fonction de vos habitudes de trafic. Des temps d'inactivité plus courts permettent de libérer de la capacité plus rapidement. ## 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-microvm`API : | Erreur | Cause | Solution | | --- | --- | --- | | ServiceQuotaExceededException | Le compte a atteint son quota de mémoire pour les micromachines virtuelles simultanées. | Mettez fin aux micromachines virtuelles inactives ou demandez une augmentation de quota. | | ResourceNotFoundException | L'image spécifiée n'existe pas ou n'est pas dans son CREATED état. | Vérifiez l'identifiant de l'image et confirmez que la création est terminée. | | ValidationException | Un ou plusieurs paramètres de demande ne sont pas valides. | Vérifiez les valeurs de politique d'inactivité, le format de l'identifiant d'image et les ARN des connecteurs. | | ThrottlingException | La limite de débit de l'API pour cette opération a été dépassée. | Implémentez un ralentissement exponentiel avec gigue. | ### 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](microvms-integrations.md)