Modifications apportées à l'utilitaire de EC2 métadonnées de la version 1 à la version 2 - AWS SDK for Java 2.x
Changements de haut niveauChangements de comportementDifférences de configuration

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.

Modifications apportées à l'utilitaire de EC2 métadonnées de la version 1 à la version 2

Cette rubrique décrit les modifications apportées à l'utilitaire de métadonnées Amazon Elastic Compute Cloud (EC2) SDK pour Java de la version 1 (v1) à la version 2 (v2).

Changements de haut niveau

Modification v1 v2

Dépendances de Maven

 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.5871</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-core</artifactId>
    </dependency>
</dependencies>
 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.27.212</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>imds</artifactId>
    </dependency>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>apache-client3</artifactId>
    </dependency>
</dependencies>
Nom du package com.amazonaws.util software.amazon.awssdk.imds
Approche d'instanciation

Utilisez des méthodes utilitaires statiques ; aucune instanciation :

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

Utilisez une méthode d'usine statique :

Ec2MetadataClient client = Ec2MetadataClient.create();

Ou utilisez une approche de constructeur :

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();
Types de clients Méthodes utilitaires synchrones uniquement : EC2MetadataUtils

Synchrone : Ec2MetadataClient

Asynchrone : Ec2MetadataAsyncClient

1 Dernière version. 2 Dernière version.

3 Notez la déclaration du apache-client module pour la v2. La version V2 de l'utilitaire de EC2 métadonnées nécessite une implémentation de l'SdkHttpClientinterface pour le client de métadonnées synchrone ou de l'SdkAsyncHttpClientinterface pour le client de métadonnées asynchrone. La HTTPclients section présente la liste des HTTP clients que vous pouvez utiliser.

Demande de métadonnées

Dans la version 1, vous utilisez des méthodes statiques qui n'acceptent aucun paramètre pour demander des métadonnées pour une EC2 ressource. En revanche, vous devez spécifier le chemin d'accès à la EC2 ressource en tant que paramètre dans la version 2. Le tableau suivant présente les différentes approches.

v1 v2 
String userMetaData = EC2MetadataUtils.getUserData();
 
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = 
                client.get("/latest/user-data");
String userMetaData = 
                response.asString();

Reportez-vous aux catégories de métadonnées de l'instance pour trouver le chemin que vous devez fournir pour demander un élément de métadonnées.

Note

Lorsque vous utilisez un client de métadonnées d'instance dans la version 2, vous devez vous efforcer d'utiliser le même client pour toutes les demandes de récupération de métadonnées.

Changements de comportement

JSONdonnées

ActivéEC2, le service de métadonnées d'instance (IMDS) exécuté localement renvoie certaines métadonnées sous JSON forme de chaînes formatées. Les métadonnées dynamiques d'un document d'identité d'instance en sont un exemple.

La v1 API contient des méthodes distinctes pour chaque élément de métadonnées d'identité d'instance, tandis que la v2 renvoie API directement la JSON chaîne. Pour travailler avec la JSON chaîne, vous pouvez utiliser le document API pour analyser la réponse et parcourir la JSON structure.

Le tableau suivant compare la manière dont vous récupérez les métadonnées d'un document d'identité d'instance dans les versions 1 et 2.

Cas d’utilisation v1 v2
Récupérez la région 
InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String region = instanceInfo.getRegion();
 
Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String region = instanceInfo.asMap().get("region").asString();
Récupérez l'identifiant de l'instance 
InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String instanceId = instanceInfo.instanceId;
 
Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceId = instanceInfo.asMap().get("instanceId").asString();
Récupérez le type d'instance 
InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String instanceType = instanceInfo.instanceType();
 
Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceType = instanceInfo.asMap().get("instanceType").asString();

Différences de résolution des terminaux

Le tableau suivant indique les emplacements vers lesquels les SDK vérifications visent à résoudre le point de terminaisonIMDS. Les emplacements sont répertoriés par ordre de priorité décroissant.

v1 v2
Propriété du système : com.amazonaws.sdk.ec2MetadataServiceEndpointOverride Méthode de configuration du générateur de clients : endpoint(...)
Variable d'environnement : AWS_EC2_METADATA_SERVICE_ENDPOINT Propriété du système : aws.ec2MetadataServiceEndpoint
Valeur par défaut: http://169.254.169.254 Fichier de configuration : ~.aws/config avec le ec2_metadata_service_endpoint paramètre
Valeur associée à la résolution endpoint-mode
Valeur par défaut : http://169.254.169.254

Résolution du point de terminaison en version 2

Lorsque vous définissez explicitement un point de terminaison à l'aide du générateur, cette valeur de point de terminaison est prioritaire par rapport à tous les autres paramètres. Lorsque le code suivant s'exécute, la propriété aws.ec2MetadataServiceEndpoint système et le ec2_metadata_service_endpoint paramètre du fichier de configuration sont ignorés s'ils existent.

Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpoint(URI.create("endpoint.to.use"))
  .build();

Mode Endpoint

Avec la version v2, vous pouvez spécifier un mode de point de terminaison pour configurer le client de métadonnées afin qu'il utilise les valeurs de point de terminaison par défaut pour ou. IPv4 IPv6 Le mode Endpoint n'est pas disponible pour la version 1. La valeur par défaut utilisée pour IPv4 est http://169.254.169.254 et http://[fd00:ec2::254] pourIPv6.

Le tableau suivant montre les différentes manières de définir le mode de point de terminaison par ordre décroissant de priorité.

Valeurs possibles
Méthode de configuration du générateur de clients : endpointMode(...) 
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();
 EndpointMode.IPV4, EndpointMode.IPV6
Propriété du système aws.ec2MetadataServiceEndpointMode IPv4, IPv6 (le cas n'a pas d'importance)
Fichier de configuration : ~.aws/config Paramètre ec2_metadata_service_endpoint IPv4, IPv6 (le cas n'a pas d'importance)
Non spécifié dans les méthodes précédentes IPv4est utilisé

Comment cela se SDK résout endpoint ou endpoint-mode en v2

  1. SDKUtilise la valeur que vous avez définie dans le code du générateur de clients et ignore les paramètres externes. Comme il SDK génère une exception si les deux endpoint endpointMode sont appelés sur le générateur de clients, il SDK utilise la valeur du point de terminaison, quelle que soit la méthode que vous utilisez.

  2. Si vous ne définissez aucune valeur dans le code, il SDK se tourne vers une configuration externe, d'abord pour les propriétés du système, puis pour un paramètre dans le fichier de configuration.

    1. La SDK première vérifie la valeur d'un point de terminaison. Si une valeur est trouvée, elle est utilisée.

    2. S'il n'a SDK toujours pas trouvé de valeur, il SDK recherche les paramètres du mode point de terminaison.

  3. Enfin, si aucun paramètre SDK externe n'est trouvé et que vous n'avez pas configuré le client de métadonnées dans le code, il SDK utilise la IPv4 valeur dehttp://169.254.169.254.

IMDSv2

Amazon EC2 définit deux approches pour accéder aux métadonnées des instances :

  • Service de métadonnées d'instance, version 1 (IMDSv1) — Approche de demande/réponse

  • Service de métadonnées d'instance version 2 (IMDSv2) — Approche axée sur les sessions

Le tableau suivant compare le fonctionnement de Java SDKs avecIMDS.

v1 v2
IMDSv2est utilisé par défaut Utilise toujours IMDSv2
Tente de récupérer un jeton de session pour chaque demande et revient à zéro IMDSv1 si elle ne parvient pas à récupérer un jeton de session Conserve un jeton de session dans un cache interne qui est réutilisé pour plusieurs demandes

La SDK version 2.x pour Java ne prend en charge que IMDSv2 et ne repose pas sur. IMDSv1

Différences de configuration

Le tableau suivant répertorie les différentes options de configuration.

Configuration v1 v2
Nouvelle tentative Configuration non disponible Configurable via la méthode du générateur retryPolicy(...)
HTTP Délai d'expiration de connexion configurable via la variable d'AWS_METADATA_SERVICE_TIMEOUTenvironnement. La valeur par défaut est de 1 seconde. Configuration disponible en passant un HTTP client à la méthode du générateurhttpClient(...). Le délai de connexion par défaut pour les HTTP clients est de 2 secondes.

Exemple de HTTP configuration v2

L'exemple suivant montre comment configurer le client de métadonnées. Cet exemple configure le délai d'expiration de la connexion et utilise le client ApacheHTTP.

SdkHttpClient httpClient = ApacheHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(1))
    .build();

Ec2MetadataClient imdsClient = Ec2MetadataClient.builder()
    .httpClient(httpClient)
    .build();