View a markdown version of this page

Accéder aux métadonnées d’une instance EC2 - Amazon Elastic Compute Cloud
Considérations sur l’accès aux métadonnées d’instanceAccédez aux métadonnées de l’instance depuis une instance EC2Interroger les options de métadonnées d’instanceRéponses et messages d’erreurLimitation des demandes

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.

Accéder aux métadonnées d’une instance EC2

Vous pouvez accéder aux métadonnées de l’instance EC2 depuis l’instance elle-même ou depuis la console EC2, l’API, les SDK ou la AWS CLI. Pour obtenir les paramètres de métadonnées d’instance actuels d’une instance à partir de la console ou de la ligne de commande, consultez Interroger les options de métadonnées d’instance pour les instances existantes.

Vous pouvez également modifier les données de l’utilisateur pour les instances avec un volume racine EBS. L’instance doit être à l’état arrêté. Pour obtenir des instructions de la console, consultez Mettre à jour les données de l’utilisateur de l’instance. Pour un exemple Linux utilisant le AWS CLI, consultez https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html modify-instance-attribute. Pour un exemple Windows utilisant les Outils pour Windows PowerShell, consultezDonnées utilisateur et outils pour Windows PowerShell.

Note

Vous n’êtes pas facturé pour les requêtes HTTP utilisées pour récupérer les métadonnées d’instance et les données utilisateur.

Considérations sur l’accès aux métadonnées d’instance

Pour éviter les problèmes liés aux métadonnées de l'instance, prenez en compte les points suivants.

Échecs de lancement d'instance dus à l'application de l'IMDSv2 () HttpTokensEnforced=enabled

Avant d'activer l'application IMDSv2, tous les logiciels de l'instance doivent prendre en charge IMDSv2. Vous pouvez ensuite modifier la valeur par défaut pour désactiver IMDSv1 (httpTokens=required), puis activer l'application. Pour plus d’informations, consultez Passer à l’utilisation de Service des métadonnées d’instance Version 2.

Format de la commande

Le format de commande est différent selon que vous utilisez Instance Metadata Service Version 1 (IMDSv1) ou Instance Metadata Service Version 2 (IMDSv2). Par défaut, vous pouvez utiliser les deux services de métadonnées d’instance. Pour imposer l’utilisation de IMDSv2, consultez Utilisez Instance Metadata Service.

Si IMDSv2 est requis, IMDSv1 ne fonctionne pas

Si vous utilisez IMDSv1 et que vous ne recevez aucune réponse, il est probable que IMDSv2 soit requis. Pour vérifier si IMDSv2 est requis, sélectionnez l’instance pour en afficher les détails. La valeur IMDSv2 indique Obligatoire (vous devez utiliser IMDSv2) ou Facultatif (vous pouvez utiliser IMDSv2 ou IMDSv1).

(IMDSv2) /latest/api/token À utiliser pour récupérer le jeton

L’envoi de requêtes PUT à tout chemin spécifique d’une version, par exemple /2021-03-23/api/token, a pour effet que le service de métadonnées retourne des erreurs 403 Interdit. Ce comportement est prévu.

Version des métadonnées

Pour éviter de devoir mettre à jour votre code chaque fois qu’Amazon EC2 publie un nouveau build des métadonnées d’instance, nous vous recommandons d’utiliser latest dans le chemin d’accès, et non le numéro de version.

Prise en charge d’IPv6

Pour récupérer les métadonnées d’instance à l’aide d’une adresse IPv6, assurez-vous d’activer et d’utiliser l’adresse IPv6 de l’IMDS [fd00:ec2::254] au lieu de l’adresse IPv4 169.254.169.254. L'instance doit être une Nitro-based instance lancée dans un sous-réseau prenant en charge IPv6.

(Windows) Créer des AMI personnalisées à l’aide de Windows Sysprep

Pour garantir le fonctionnement de l’IMDS lorsque vous lancez une instance à partir d’une AMI Windows personnalisée, l’AMI doit être une image standardisée créée avec Windows Sysprep. Sinon, l’IMDS ne fonctionnera pas. Pour de plus amples informations, veuillez consulter Créer une AMI Amazon EC2 à l’aide de Windows Sysprep.

Dans un environnement de conteneurs, envisagez de reconfigurer ou d’augmenter la limite de saut à 2

Les AWS SDK utilisent les appels IMDSv2 par défaut. Si l'appel IMDSv2 ne reçoit aucune réponse, certains AWS SDK relancent l'appel et, en cas d'échec, utilisent IMDSv1. Cela peut entraîner un retard, en particulier dans un environnement de conteneurs. Pour les AWS SDK qui nécessitent IMDSv2, si la limite de sauts est de 1 dans un environnement de conteneur, l'appel risque de ne pas recevoir de réponse car l'accès au conteneur est considéré comme un saut réseau supplémentaire.

Pour atténuer ces problèmes dans un environnement de conteneur, envisagez de modifier la configuration pour transmettre les paramètres (tels que le Région AWS) directement au conteneur, ou envisagez d'augmenter la limite de sauts à 2. Pour en savoir plus sur l’impact de la limite de saut, consultez la section Ajout d’une défense en profondeur contre les pare-feu ouverts, les proxys inversés et les vulnérabilités SSRF grâce aux améliorations apportées au service de métadonnées d’instance EC2. Pour plus d’informations sur la modification de la limite de saut, consultez la section Modifier la durée de vie de la réponse PUT.

Limite de paquets par seconde (PPS)

Il existe une limite de 1024 paquets par seconde (PPS) pour les services qui utilisent des adresses lien-local. Cette limite inclut l’ensemble des requêtes DNS du résolveur Route 53, des demandes IMDS (Instance Metadata Service), des demandes NTP (Amazon Time Service Network Time Protocol) et des demandes du Windows Licensing Service (pour les instances basées sur Microsoft Windows).

Considérations supplémentaires sur l’accès aux données utilisateur

  • Les données utilisateur sont traitées comme des données opaques : ce que vous spécifiez est ce que vous obtenez en retour. Il appartient à l’instance d’interpréter et d’agir sur les données utilisateur.

  • Les données utilisateur doivent être codées en base64. Selon l’outil ou le SDK que vous utilisez, le codage base64 peut être effectué pour vous. Par exemple :

    • La console Amazon EC2 peut effectuer l’encodage base64 pour vous ou accepter les entrées codées en base64.

    • AWS CLI la version 2 effectue le codage base64 des paramètres binaires pour vous par défaut. AWS CLI la version 1 effectue le codage base64 du --user-data paramètre pour vous.

    • AWS SDK pour Python (Boto3) Effectue le codage en base64 du UserData paramètre pour vous.

  • Les données d’utilisateur sont limitées à 16 Ko en format brut, avant qu’elles soient encodées en base64. La taille d’une chaîne de longueur n après l’encodage base64 est ceil(n/3)*4.

  • Les données utilisateur doivent être décodées en base64 lorsque vous les récupérez. Si vous les récupérez à l’aide des métadonnées d’instance ou de la console, les données sont décodées automatiquement.

  • Si vous arrêtez une instance, modifiez ses données utilisateur et démarrez l’instance, les données utilisateur mises à jour ne sont pas exécutées automatiquement lorsque vous démarrez l’instance. En ce qui concerne les instances Windows, vous pouvez configurer les paramètres de manière à ce que les scripts de données utilisateur mis à jour soient exécutés une fois au démarrage de l’instance ou à chaque redémarrage ou démarrage de l’instance.

  • Les données utilisateur sont un attribut d’instance. Si vous créez une AMI à partir d’une instance, les données utilisateur d’instance ne sont pas incluses dans l’AMI.

Accédez aux métadonnées de l’instance depuis une instance EC2

Puisque vos métadonnées d’instance sont disponibles à partir de votre instance en cours d’exécution, vous n’avez pas besoin d’utiliser la console Amazon EC2, ni la AWS CLI. Cela peut être utile lorsque vous écrivez des scripts à exécuter depuis votre instance. Par exemple, vous pouvez accéder à l’adresse IP locale de votre instance à partir des métadonnées d’instance afin de gérer une connexion à une application externe.

Tous les éléments suivants sont considérés comme des métadonnées d’instance, mais ils sont accessibles de différentes manières. Sélectionnez l’onglet qui représente le type de métadonnées d’instance auquel vous souhaitez accéder pour obtenir plus d’informations.

Metadata

Les propriétés des métadonnées d’instance sont divisées en catégories. Pour obtenir une description de chaque catégorie de métadonnées d’instance, consultez Catégories de métadonnées d’instance.

Pour accéder aux propriétés des métadonnées d’instance à partir d’une instance en cours d’exécution, récupérez les données à partir des URI IPv4 ou IPv6 ci-après. Ces adresses IP sont des adresses locales et ne sont valables qu’à partir de l’instance. Pour de plus amples informations, veuillez consulter Link-local adresses.

IPv4

http://169.254.169.254/latest/meta-data/

IPv6

http://[fd00:ec2::254]/latest/meta-data/
Dynamic data

Pour récupérer des données dynamiques à partir d’une instance en cours d’exécution, utilisez l’un des URI suivants.

IPv4

http://169.254.169.254/latest/dynamic/

IPv6

http://[fd00:ec2::254]/latest/dynamic/
Exemples : accès avec cURL

Les exemples suivants permettent cURL de récupérer les catégories d’identité d’instance de haut niveau.

IMDSv2

[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/dynamic/instance-identity/
rsa2048
pkcs7
document
signature
dsa2048

IMDSv1

[ec2-user ~]$ curl http://169.254.169.254/latest/dynamic/instance-identity/
rsa2048
pkcs7
document
signature
dsa2048
Exemples : Accès avec PowerShell

Les exemples suivants permettent PowerShell de récupérer les catégories d'identité d'instance de haut niveau.

IMDSv2

PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/dynamic/instance-identity/
document
rsa2048
pkcs7
signature

IMDSv1

PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/dynamic/instance-identity/
document
rsa2048
pkcs7
signature

Pour plus d’informations sur les données dynamiques et pour des exemples sur la façon de les récupérer, consultez Documents d’identité d’instance pour les instances Amazon EC2.

User data

Pour récupérer les données utilisateur d’une instance, utilisez l’un des URI suivants. Pour récupérer les données utilisateur à l'aide de l'adresse IPv6, vous devez l'activer et l'instance doit être une Nitro-based instance d'un sous-réseau prenant en charge IPv6.

IPv4

http://169.254.169.254/latest/user-data

IPv6

http://[fd00:ec2::254]/latest/user-data

Une demande de données utilisateur renvoie les données telles qu’elles sont (type de contenu application/octet-stream). Si l’instance ne possède aucune donnée utilisateur, la demande renvoie 404 - Not Found.

Exemples : Accès avec cURL pour récupérer du texte séparé par des virgules

Les exemples suivants permettent de cURL récupérer des données utilisateur qui ont été spécifiées sous la forme de texte séparé par des virgules.

IMDSv2

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

curl http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
Exemples : Accédez avec PowerShell pour récupérer du texte séparé par des virgules

Les exemples suivants permettent PowerShell de récupérer les données utilisateur spécifiées sous forme de texte séparé par des virgules.

IMDSv2

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} `
-Method PUT -Uri http://169.254.169.254/latest/api/token} -Method GET -uri http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
Exemples : Accès avec cURL pour récupérer un script

Les exemples suivants permettent cURL de récupérer des données utilisateur qui ont été spécifiées sous la forme d’un script.

IMDSv2

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

IMDSv1

curl http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
Exemples : Accédez avec PowerShell pour récupérer un script

Les exemples suivants permettent PowerShell de récupérer les données utilisateur spécifiées sous forme de script.

IMDSv2

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data
<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>

IMDSv1

Invoke-RestMethod -uri http://169.254.169.254/latest/user-data
<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>

Interroger les options de métadonnées d’instance pour les instances existantes

Vous pouvez modifier les options des métadonnées d’instance pour les instances existantes.

Console
Pour interroger les options de métadonnées d’instance pour une instance existante

  1. Ouvrez la console Amazon EC2 à l’adresse https://console.aws.amazon.com/ec2/.

  2. Dans le panneau de navigation, choisissez Instances.

  3. Sélectionnez votre instance et vérifiez les champs suivants :

    • IMDSv2 : la valeur est Obligatoire ou Facultatif.

    • Autoriser les balises dans les métadonnées de l’instance : la valeur est Activé ou Désactivé.

  4. Choisissez Actions, Paramètres de l’instance, puis Modifier les options des métadonnées d’instance.

    La boîte de dialogue indique si le service de métadonnées d’instance est activé ou désactivé pour l’instance sélectionnée.

AWS CLI
Pour interroger les options de métadonnées d’instance pour une instance existante

Utilisez la commande describe-instances.

aws ec2 describe-instances \
    --instance-id i-1234567898abcdef0 \
    --query 'Reservations[].Instances[].MetadataOptions'
PowerShell
Pour interroger les options de métadonnées d'une instance existante à l'aide des Outils pour PowerShell

Utilisez l’applet de commande Get-EC2Instance.

(Get-EC2Instance `
    -InstanceId i-1234567898abcdef0).Instances.MetadataOptions

Réponses et messages d’erreur

Toutes les métadonnées d’instance sont retournées sous forme de texte (type de contenu HTTP text/plain).

Une requête pour une ressource de métadonnées spécifique retourne la valeur appropriée ou un code d’erreur HTTP 404 - Not Found si la ressource n’est pas disponible.

Une requête pour une ressource de métadonnées générale (l’URI se termine par un /) retourne une liste de ressources disponibles ou un code d’erreur HTTP 404 - Not Found si une telle ressource n’existe pas. Les éléments de la liste se trouvent sur des lignes séparées se terminant par des sauts de ligne (ASCII 10).

Si une requête IMDSv1 ne reçoit pas de réponse, il est probable qu’IMDSv2 soit nécessaire.

Pour les demandes effectuées à l’aide d’IMDSv2, les codes d’erreur HTTP suivants peuvent être renvoyés :

  • 400 - Missing or Invalid Parameters – La demande PUT n’est pas valide.

  • 401 - Unauthorized – La demande GET utilise un jeton non valide. Il est recommandé dans ce cas de générer un nouveau jeton.

  • 403 - Forbidden : la demande n’est pas autorisée ou l’IMDS est désactivé.

  • 404 - Not Found : la ressource n’est pas disponible ou n’existe pas.

  • 503 : la demande n’a pas pu être exécutée. Réitérez la demande.

Si l’IMDS renvoie une erreur, curl imprime le message d’erreur dans la sortie et renvoie un code d’état de réussite. Le message d’erreur est stocké dans la variable TOKEN, ce qui entraîne l’échec des commandes curl utilisant le jeton. Si vous appelez curl à l’aide de l’option -f, elle renvoie un code d’état d’erreur en cas d’erreur du serveur HTTP. Si vous activez la gestion des erreurs, le shell peut détecter l’erreur et arrêter le script.

Limitation des demandes

Nous limitons les requêtes envoyées par chaque instance à l’IMDS et appliquons des limites au nombre de connexions simultanées possible depuis une instance vers l’IMDS.

Si vous utilisez l'IMDS pour récupérer des informations de AWS sécurité, évitez de demander des informations d'identification à chaque transaction ou simultanément à partir d'un grand nombre de threads ou de processus, car cela pourrait entraîner une limitation. Nous vous conseillons plutôt de placer les informations d’identification en cache jusqu’à ce que leur date d’expiration approche. Pour plus d’informations sur le rôle IAM et les informations d’identification de sécurité associées au rôle, consultez Extraire les informations d’identification de sécurité à partir des métadonnées d’instance.

Si vous rencontrez des limitations alors que vous tentez d’accéder à l’IMDS, renvoyez une requête avec une stratégie de backoff exponentiel.