View a markdown version of this page

Modifications apportées à l'utilitaire de métadonnées EC2 de la version 1 à la version 2 - AWS SDK for Java 2.x
High-level modificationsChangements 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 métadonnées EC2 de la version 1 à la version 2

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

High-level modifications

Modifier v1   v2

Dépendances avec 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 ; pas d'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 2 de l'utilitaire de métadonnées EC2 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 Configurez les clients HTTP dans AWS SDK for Java 2.x section présente la liste des clients HTTP 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 ressource EC2. En revanche, vous devez spécifier le chemin d'accès à la ressource EC2 en tant que paramètre dans la v2. 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 d'instance pour trouver le chemin que vous devez fournir pour demander une métadonnée.

Note

Lorsque vous utilisez un client de métadonnées d'instance dans la v2, 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

Données JSON

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

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

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 v1 et v2.

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 que le SDK vérifie pour résoudre le point de terminaison en IMDS. 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 réglage
Valeur associée à la résolution endpoint-mode
Valeur par défaut : http://169.254.169.254

Résolution des terminaux dans la v2

Lorsque vous définissez explicitement un point de terminaison à l'aide du générateur, cette valeur de point de terminaison est prioritaire sur 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();

Endpoint-mode

Avec la 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 IPv4 ou IPv6. Endpoint-mode n'est pas disponible pour la v1. La valeur par défaut utilisée pour IPv4 est http://169.254.169.254 et http://[fd00:ec2::254] pour IPv6.

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

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 IPv4 est utilisé

Comment le SDK résout le point de terminaison ou le mode point de terminaison dans la v2

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

  2. Si vous ne définissez aucune valeur dans le code, le 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. Le SDK vérifie d'abord la valeur d'un point de terminaison. Si une valeur est trouvée, elle est utilisée.

    2. Si le SDK n'a toujours pas trouvé de valeur, il recherche les paramètres du mode Endpoint.

  3. Enfin, si le SDK ne trouve aucun paramètre externe et que vous n'avez pas configuré le client de métadonnées dans le code, le SDK utilise la valeur IPv4 de. http://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 Request/response

  • Service de métadonnées d'instance, version 2 (IMDSv2) : approche Session-oriented

Le tableau suivant compare le fonctionnement des SDK Java avec IMDS.

v1   v2
IMDSv2 est utilisé par défaut Utilise toujours IMDSv2
Tente de récupérer un jeton de session pour chaque demande et revient à IMDSv1 s'il 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

Le SDK pour Java 2.x ne prend en charge que IMDSv2 et ne revient pas à IMDSv1.

Différences de configuration

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

Configuration v1   v2
Nouvelles tentatives Configuration non disponible Configurable via la méthode du générateur retryPolicy(...)
HTTP Délai 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 client HTTP à la méthode du générateurhttpClient(...). Le délai de connexion par défaut pour les clients HTTP est de 2 secondes.

Exemple de configuration HTTP v2

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

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

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