Cambios en la utilidad de metadatos de EC2 de la versión 1 a versión 2 - AWS SDK for Java 2.x
Cambios de alto nivelCambios de comportamientoDiferencias de configuración

Cambios en la utilidad de metadatos de EC2 de la versión 1 a versión 2

En este tema se detallan los cambios en la utilidad de metadatos Amazon Elastic Compute Cloud (EC2) del SDK para Java de la versión 1 (v1) a la versión 2 (v2).

Cambios de alto nivel

Cambio v1 v2

dependencias 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>
Package name com.amazonaws.util software.amazon.awssdk.imds
Enfoque de instanciación

Utilice métodos de utilidad estáticos; sin instanciación:

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

Utilice un método de fábrica estático:

Ec2MetadataClient client = Ec2MetadataClient.create();

O utilice un enfoque de creación:

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();
Tipos de clientes Métodos de utilidad únicamente síncronos: EC2MetadataUtils

Síncrono: Ec2MetadataClient

Asíncrono: Ec2MetadataAsyncClient

1 Última versión. 2 Última versión.

3 Observe la declaración del módulo apache-client para la versión 2. La versión 2 de la utilidad de metadatos EC2 requiere una implementación de la interfaz SdkHttpClient para el cliente de metadatos síncrono o la interfaz SdkAsyncHttpClient para el cliente de metadatos asíncrono. La sección Configuración de clientes de HTTP en AWS SDK for Java 2.x muestra la lista de clientes HTTP que puede utilizar.

Solicitar metadatos

En la versión 1, se utilizan métodos estáticos que no aceptan parámetros para solicitar metadatos para un recurso de EC2. Por el contrario, debe especificar la ruta al recurso de EC2 como parámetro en la v2. En la tabla siguiente, se muestran los diferentes enfoques.

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

Consulte las categorías de metadatos de la instancia para encontrar la ruta que necesita proporcionar para solicitar un fragmento de metadatos.

nota

Cuando utilice un cliente de metadatos de instancia en la versión 2, debe intentar usar el mismo cliente para todas las solicitudes de recuperación de metadatos.

Cambios de comportamiento

Datos JSON

En EC2, el Servicio de metadatos de instancias (IMDS) que se ejecuta localmente devuelve algunos metadatos en forma de cadenas con formato JSON. Un ejemplo de ello son los metadatos dinámicos de un documento de identidad de instancias.

La API v1 contiene métodos independientes para cada elemento de metadatos de identidad de la instancia, mientras que la API v2 devuelve directamente la cadena JSON. Para trabajar con la cadena JSON, puede usar la API de documentos para analizar la respuesta y navegar por la estructura JSON.

En la siguiente tabla, se compara la forma de recuperar los metadatos de un documento de identidad de instancia en las versiones 1 y 2.

Caso de uso v1 v2
Recuperar la región 
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 el identificador de la instancia 
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 el tipo de la instancia 
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();

Diferencias en la resolución de punto de conexión

La siguiente tabla muestra las ubicaciones que el SDK comprueba para resolver el punto de conexión en el IMDS. Las ubicaciones se muestran en orden de prioridad descendente.

v1 v2
Propiedad del sistema: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride Método de configuración del creador de clientes: endpoint(...)
Variable de entorno: AWS_EC2_METADATA_SERVICE_ENDPOINT Propiedad del sistema: aws.ec2MetadataServiceEndpoint
Valor predeterminado: : http://169.254.169.254 Archivo de configuración: ~.aws/config con la configuración ec2_metadata_service_endpoint
Valor asociado a endpoint-mode resuelto
Valor predeterminado: #: http://169.254.169.254

Resolución del punto de conexión en la versión 2

Cuando se establece explícitamente un punto de conexión mediante el creador, el valor de ese punto de conexión tiene prioridad sobre todos los demás ajustes. Cuando se ejecuta el siguiente código, la propiedad del sistema aws.ec2MetadataServiceEndpoint y el ajuste ec2_metadata_service_endpoint del archivo de configuración se ignoran si existen.

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

Modo de punto de conexión

Con la versión 2, puede especificar un modo de punto de conexión para configurar el cliente de metadatos de modo que utilice los valores de punto de conexión predeterminados para IPv4 o IPv6. El modo de punto de conexión no está disponible para la versión 1. El valor predeterminado utilizado para IPv4 es http://169.254.169.254 y http://[fd00:ec2::254] para IPv6.

En la siguiente tabla se muestran las distintas formas de configurar el modo de punto de conexión en orden descendente de prioridad.

Valores posibles
Método de configuración del creador de clientes: endpointMode(...) 
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();
 EndpointMode.IPV4, EndpointMode.IPV6
Propiedad del sistema aws.ec2MetadataServiceEndpointMode IPv4, IPv6 (no distingue entre mayúsculas y minúsculas)
Archivo de configuración: ~.aws/config ec2_metadata_service_endpointAjuste IPv4, IPv6 (no distingue entre mayúsculas y minúsculas)
No especificado de las formas anteriores Se utiliza IPv4

Cómo resuelve el SDK endpoint o endpoint-mode en la versión 2

  1. El SDK usa el valor que se establece en el código del creador de clientes e ignora cualquier configuración externa. Como el SDK genera una excepción si ambos endpoint y endpointMode se invocan en el creador de clientes, el SDK usa el valor de punto de conexión del método que utilice.

  2. Si no establece un valor en el código, el SDK busca en la configuración externa primero las propiedades del sistema y, después, una configuración en el archivo de configuración.

    1. El SDK primero comprueba si hay un valor de punto de conexión. Si se encuentra un valor, se usa.

    2. Si el SDK sigue sin encontrar ningún valor, busca la configuración del modo de punto de conexión.

  3. Por último, si el SDK no encuentra ninguna configuración externa y no ha configurado el cliente de metadatos en código, el SDK utiliza el valor IPv4 de http://169.254.169.254.

IMDSv2

Amazon EC2 define dos enfoques para acceder a los metadatos de las instancias:

  • Servicio de metadatos de instancia, versión 1 (IMDSv1): enfoque de solicitud y respuesta

  • Servicio de metadatos de instancia, versión 2 (IMDSv2): enfoque orientado a la sesión

En la siguiente tabla se compara el funcionamiento de los SDK de Java con el IMDS.

v1 v2
IMDSv2 se usa de forma predeterminada Siempre usa IMDSv2
Intenta obtener un token de sesión para cada solicitud y recurre a IMDSv1 si no logra obtener un token de sesión Mantiene un token de sesión en una caché interna que se reutiliza para múltiples solicitudes

El SDK para Java 2.x solo admite IMDSv2 y no recurre a IMDSv1.

Diferencias de configuración

En la tabla siguiente se muestran las diferentes opciones de configuración.

Configuración v1 v2
Reintentos La configuración no está disponible Configurable mediante el método de creador retryPolicy(...)
HTTP El tiempo de espera de la conexión se puede configurar mediante la variable de entorno de AWS_METADATA_SERVICE_TIMEOUT. El valor predeterminado es de 1 segundo. La configuración está disponible pasando un cliente HTTP al método de creador httpClient(...). El tiempo de espera de conexión predeterminado para los clientes HTTP es de 2 segundos.

Ejemplo de configuración HTTP v2

En el siguiente ejemplo, se muestra cómo se puede configurar el cliente de metadatos. En este ejemplo se configura el tiempo de espera de la conexión y se utiliza el cliente HTTP Apache.

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

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