Modifiche nell'utilità per i metadati EC2 dalla versione 1 alla versione 2 - AWS SDK for Java 2.x
Modifiche di alto livelloModifiche al comportamentoDifferenze di configurazione

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Modifiche nell'utilità per i metadati EC2 dalla versione 1 alla versione 2

Questo argomento descrive in dettaglio le modifiche all'utilità di metadati SDK for Java Amazon Elastic Compute Cloud (EC2) dalla versione 1 (v1) alla versione 2 (v2).

Modifiche di alto livello

Modifica v1 v2

Dipendenze da 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.21.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>
Nome pacchetto com.amazonaws.util software.amazon.awssdk.imds
Approccio all'istanziazione

Utilizza metodi di utilità statici; nessuna istanziazione:

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

Usa un metodo di fabbrica statico:

Ec2MetadataClient client = Ec2MetadataClient.create();

Oppure usa un approccio da costruttore:

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();
Tipi di clienti Metodi di utilità solo sincroni: EC2MetadataUtils

Sincrono: Ec2MetadataClient

Asincrono: Ec2MetadataAsyncClient

1 Ultima versione. 2 Ultima versione.

3 Notate la dichiarazione del apache-client modulo per la v2. La versione 2 dell'utilità per i metadati EC2 richiede l'implementazione dell'interfaccia per il client di metadati sincrono o dell'SdkHttpClientinterfaccia per il client di metadati asincrono. SdkAsyncHttpClient La Client HTTP sezione mostra l'elenco dei client HTTP che è possibile utilizzare.

Richiesta di metadati

Nella v1, si utilizzano metodi statici che non accettano parametri per richiedere i metadati per una risorsa EC2. Al contrario, è necessario specificare il percorso della risorsa EC2 come parametro nella v2. La tabella seguente mostra i diversi approcci.

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

Fate riferimento alle categorie di metadati delle istanze per trovare il percorso da fornire per richiedere una parte di metadati.

Nota

Quando utilizzi un client di metadati di istanza nella v2, dovresti mirare a utilizzare lo stesso client per tutte le richieste di recupero dei metadati.

Modifiche al comportamento

Dati JSON

In EC2, l'Instance Metadata Service (IMDS) in esecuzione locale restituisce alcuni metadati come stringhe in formato JSON. Uno di questi esempi sono i metadati dinamici di un documento di identità di istanza.

L'API v1 contiene metodi separati per ogni parte dei metadati di identità dell'istanza, mentre l'API v2 restituisce direttamente la stringa JSON. Per lavorare con la stringa JSON, puoi utilizzare l'API Document per analizzare la risposta e navigare nella struttura JSON.

La tabella seguente confronta il modo in cui recuperi i metadati di un documento di identità di istanza in v1 e v2.

Caso d'uso v1 v2
Recupera la regione 
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();
Recupera l'id dell'istanza 
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();
Recupera il tipo di istanza 
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();

Differenze di risoluzione degli endpoint

La tabella seguente mostra le posizioni controllate dall'SDK per risolvere l'endpoint in IMDS. Le posizioni sono elencate con priorità decrescente.

v1 v2
Proprietà del sistema: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride Metodo di configurazione di Client Builder: endpoint(...)
Variabile d'ambiente: AWS_EC2_METADATA_SERVICE_ENDPOINT Proprietà del sistema: aws.ec2MetadataServiceEndpoint
Valore predefinito: http://169.254.169.254 File di configurazione: ~.aws/config con l'impostazione ec2_metadata_service_endpoint
Valore associato a risolto endpoint-mode
Valore predefinito: http://169.254.169.254

Risoluzione dell'endpoint in v2

Quando imposti esplicitamente un endpoint utilizzando il builder, quel valore dell'endpoint ha la priorità su tutte le altre impostazioni. Quando viene eseguito il codice seguente, la proprietà di aws.ec2MetadataServiceEndpoint sistema e l'ec2_metadata_service_endpointimpostazione del file di configurazione vengono ignorate, se esistono.

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

modalità Endpoint

Con la v2, è possibile specificare una modalità endpoint per configurare il client di metadati in modo che utilizzi i valori di endpoint predefiniti per IPv4 o IPv6. La modalità endpoint non è disponibile per la versione 1. Il valore predefinito utilizzato per IPv4 è e per IPv6. http://169.254.169.254 http://[fd00:ec2::254]

La tabella seguente mostra i diversi modi in cui è possibile impostare la modalità endpoint in ordine di priorità decrescente.

Valori possibili
Metodo di configurazione di Client Builder: endpointMode(...) 
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();
 EndpointMode.IPV4, EndpointMode.IPV6
Proprietà del sistema aws.ec2MetadataServiceEndpointMode IPv4, IPv6 (il caso non ha importanza)
File di configurazione: ~.aws/config ec2_metadata_service_endpointImpostazione IPv4, IPv6 (il caso non ha importanza)
Non specificato nei modi precedenti Viene utilizzato IPv4

Come si risolve l'SDK o nella v2 endpointendpoint-mode

  1. L'SDK utilizza il valore impostato nel codice nel client builder e ignora qualsiasi impostazione esterna. Poiché l'SDK genera un'eccezione se entrambi endpoint endpointMode vengono chiamati sul client builder, l'SDK utilizza il valore dell'endpoint indipendentemente dal metodo utilizzato.

  2. Se non imposti un valore nel codice, l'SDK esamina la configurazione esterna, prima per le proprietà del sistema e poi per un'impostazione nel file di configurazione.

    1. L'SDK verifica innanzitutto il valore di un endpoint. Se viene trovato un valore, viene utilizzato.

    2. Se l'SDK non ha ancora trovato un valore, l'SDK cerca le impostazioni della modalità endpoint.

  3. Infine, se l'SDK non trova impostazioni esterne e non hai configurato il client di metadati nel codice, l'SDK utilizza il valore IPv4 di. http://169.254.169.254

IMDSv2

Amazon EC2 definisce due approcci per accedere ai metadati delle istanze:

  • Instance Metadata Service versione 1 (IMDSv1): approccio di richiesta/risposta

  • Instance Metadata Service versione 2 (IMDSv2): approccio orientato alla sessione

La tabella seguente confronta il modo in cui gli SDK Java funzionano con IMDS.

v1 v2
IMDSv2 viene utilizzato per impostazione predefinita Usa sempre IMDSv2
Tenta di recuperare un token di sessione per ogni richiesta e torna a IMDSv1 se non riesce a recuperare un token di sessione Mantiene un token di sessione in una cache interna che viene riutilizzata per più richieste

L'SDK for Java 2.x supporta solo IMDSv2 e non ricorre a IMDSv1.

Differenze di configurazione

La tabella seguente elenca le diverse opzioni di configurazione.

Configurazione v1 v2
Tentativi Configurazione non disponibile Configurabile tramite il metodo builder retryPolicy(...)
HTTP Timeout di connessione configurabile tramite la variabile di ambiente. AWS_METADATA_SERVICE_TIMEOUT L'impostazione predefinita è 1 secondo. Configurazione disponibile passando un client HTTP al metodo httpClient(...) builder. Il timeout di connessione predefinito per i client HTTP è di 2 secondi.

Esempio di configurazione HTTP v2

L'esempio seguente mostra come configurare il client di metadati. Questo esempio configura il timeout della connessione e utilizza il client HTTP Apache.

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

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