Utiliser les métadonnées d'instance Amazon EC2

Un client SDK Java pour le service de métadonnées d'instance Amazon EC2 (client de métadonnées) permet à vos applications d'accéder aux métadonnées sur leur instance EC2 locale. Le client de métadonnées fonctionne avec l'instance locale d'IMDSv2 (Instance Metadata Service v2) et utilise des requêtes orientées session.

Deux classes de clients sont disponibles dans le SDK. Le mode synchroneEc2MetadataClient est destiné aux opérations de blocage et le mode synchrone Ec2MetadataAsyncClientest destiné aux cas d'utilisation asynchrones et non bloquants.

Mise en route

Pour utiliser le client de métadonnées, ajoutez l'artefactimds Maven à votre projet. Vous avez également besoin de classes pour unSdkHttpClient (ou unSdkAsyncHttpClient pour le variant asynchrone) sur le classpath.

Le code XML Maven suivant présente des extraits de dépendance pour l'utilisation du synchrone UrlConnectionHttpClientainsi que la dépendance pour les clients de métadonnées.

<dependencyManagement>
   <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>VERSION</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>url-connection-client</artifactId>
    </dependency>
    <!-- other dependencies --> 
</dependencies>

Recherchez la dernière version de l'bomartefact dans le référentiel central de Maven.

Pour utiliser un client HTTP asynchrone, remplacez l'extrait de dépendance de l'url-connection-clientartefact. Par exemple, l'extrait suivant introduit l'NettyNioAsyncHttpClientimplémentation.

    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>netty-nio-client</artifactId>
    </dependency>

Utiliser le client de métadonnées

Instancier un client de métadonnées

Vous pouvez instancier une instance d'un objet synchroneEc2MetadataClient lorsqu'une seule implémentation de l'SdkHttpClientinterface est présente sur le classpath. Pour ce faire, appelez laEc2MetadataClient#create() méthode statique, comme illustré dans l'extrait suivant.

Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.

Si votre application possède plusieurs implémentations de l'SdkHttpAsyncClientinterfaceSdkHttpClient or, vous devez spécifier une implémentation que le client de métadonnées doit utiliser, comme indiqué dans laClient HTTP configurable section.

Note

Pour la plupart des clients de service, tels qu'Amazon S3, le SDK for Java ajoute automatiquement des implémentations de l'SdkHttpAsyncClientinterfaceSdkHttpClient or. Si votre client de métadonnées utilise la même implémentation, celaEc2MetadataClient#create() fonctionnera. Si vous avez besoin d'une implémentation différente, vous devez la spécifier lors de la création du client de métadonnées.

Envoyer des demandes

Pour récupérer les métadonnées de l'instance, instanciez laEC2MetadataClient classe et appelez laget méthode avec un paramètre de chemin qui spécifie la catégorie de métadonnées de l'instance.

L'exemple suivant imprime la valeur associée à laami-id clé sur la console.

Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/ami-id");
System.out.println(response.asString());
client.close(); // Closes the internal resources used by the Ec2MetadataClient class.

Si le chemin n'est pas valide, laget méthode génère une exception.

Réutilisez la même instance client pour plusieurs demandes, mais appelezclose le client lorsqu'il n'est plus nécessaire de libérer des ressources. Une fois la méthode close appelée, l'instance client ne peut plus être utilisée.

Analyser les réponses

Les métadonnées de l'instance EC2 peuvent être sorties dans différents formats. Le texte brut et le JSON sont les formats les plus couramment utilisés. Les clients de métadonnées offrent des moyens de travailler avec ces formats.

Comme le montre l'exemple suivant, utilisez laasString méthode pour obtenir les données sous forme de chaîne Java. Vous pouvez également utiliser laasList méthode pour séparer une réponse en texte brut qui renvoie plusieurs lignes.

Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List<String> splits = response.asList();

Si la réponse est au format JSON, utilisez laEc2MetadataResponse#asDocument méthode pour analyser la réponse JSON dans une instance de Document, comme indiqué dans l'extrait de code suivant.

Document fullResponse = response.asDocument();

Une exception sera émise si le format des métadonnées n'est pas au format JSON. Si la réponse est analysée avec succès, vous pouvez utiliser l'API du document pour inspecter la réponse plus en détail. Consultez le tableau des catégories de métadonnées d'instance pour savoir quelles catégories de métadonnées fournissent des réponses au format JSON.

Configuration d'un client de métadonnées

Retries

Vous pouvez configurer un client de métadonnées avec un mécanisme de nouvelle tentative. Dans ce cas, le client peut réessayer automatiquement les demandes qui échouent pour des raisons inattendues. Par défaut, le client réessaie trois fois en cas d'échec d'une demande, avec un délai d'attente exponentiel entre les tentatives.

Si votre cas d'utilisation nécessite un mécanisme de nouvelle tentative différent, vous pouvez personnaliser le client à l'aide de laretryPolicy méthode de son générateur. Par exemple, l'exemple suivant montre un client synchrone configuré avec un délai fixe de deux secondes entre les tentatives et cinq nouvelles tentatives.

BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
                                                                           .backoffStrategy(fixedBackoffStrategy))
                     .build();

Il en existe plusieurs BackoffStrategiesque vous pouvez utiliser avec un client de métadonnées.

Vous pouvez également désactiver complètement le mécanisme de nouvelle tentative, comme le montre l'extrait suivant.

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                    .retryPolicy(Ec2MetadataRetryPolicy.none())
                    .build();

L'utilisationEc2MetadataRetryPolicy#none() désactive la politique de nouvelle tentative par défaut afin que le client de métadonnées ne tente aucune nouvelle tentative.

Version IP

Par défaut, un client de métadonnées utilise le point de terminaison IPV4 surhttp://169.254.169.254. Pour modifier le client afin qu'il utilise la version IPV6, utilisezendpointMode soit laendpoint méthode du générateur. Une exception se produit si les deux méthodes sont appelées sur le générateur.

Les exemples suivants illustrent les deux options IPV6.

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .endpointMode(EndpointMode.IPV6)
                     .build();

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .endpoint(URI.create("http://[fd00:ec2::254]"))
                     .build();

Fonctions principales

Client asynchrone

Pour utiliser la version non bloquante du client, instanciez une instance de laEc2MetadataAsyncClient classe. Le code de l'exemple suivant crée un client asynchrone avec des paramètres par défaut et utilise laget méthode pour récupérer la valeur de laami-id clé.

Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture<Ec2MetadataResponse> response = asyncClient.get("/latest/meta-data/ami-id");

Le résultatjava.util.concurrent.CompletableFuture renvoyé par laget méthode se termine lorsque la réponse est renvoyée. L'exemple suivant imprime lesami-id métadonnées sur la console.

response.thenAccept(metadata -> System.out.println(metadata.asString()));

Client HTTP configurable

Le générateur de chaque client de métadonnées dispose d'unehttpClient méthode que vous pouvez utiliser pour fournir un client HTTP personnalisé.

L'exemple suivant présente le code pour uneUrlConnectionHttpClient instance personnalisée.

SdkHttpClient httpClient =
    UrlConnectionHttpClient.builder()
                           .socketTimeout(Duration.ofMinutes(5))
                           .proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.example.net:8888"))))
                           .build();
Ec2MetadataClient metaDataClient =
    Ec2MetadataClient.builder()
                     .httpClient(httpClient)
                     .build();
// Use the metaDataClient instance.
metaDataClient.close();   // Close the instance when no longer needed.

L'exemple suivant montre le code d'uneNettyNioAsyncHttpClient instance personnalisée avec un client de métadonnées asynchrone.

SdkAsyncHttpClient httpAsyncClient = 
    NettyNioAsyncHttpClient.builder()
                           .connectionTimeout(Duration.ofMinutes(5))
                           .maxConcurrency(100)
                           .build();
Ec2MetadataAsyncClient asyncMetaDataClient =
    Ec2MetadataAsyncClient.builder()
                          .httpClient(httpAsyncClient)
                          .build();
// Use the asyncMetaDataClient instance.
asyncMetaDataClient.close();   // Close the instance when no longer needed.

LaClients HTTP rubrique de ce guide explique en détail comment configurer les clients HTTP disponibles dans le SDK for Java.

Mise en cache de jetons

Comme les clients de métadonnées utilisent IMDSv2, toutes les demandes sont associées à une session. Une session est définie par un jeton qui a une date d'expiration, que le client de métadonnées gère pour vous. Chaque demande de métadonnées réutilise automatiquement le jeton jusqu'à son expiration.

Par défaut, un jeton dure six heures (21 600 secondes). Nous vous recommandons de conserver la time-to-live valeur par défaut, sauf si votre cas d'utilisation spécifique nécessite une configuration avancée.

Si nécessaire, configurez la durée à l'aide de la méthode dutokenTtl générateur. Par exemple, le code de l'extrait suivant crée un client dont la durée de session est de cinq minutes.

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .tokenTtl(Duration.ofMinutes(5))
                     .build();

Si vous omettez d'appeler latokenTtl méthode sur le générateur, la durée par défaut de 21 600 est utilisée à la place.