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

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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

En este tema se detallan los cambios en la utilidad de metadatos Amazon Elastic Compute Cloud (EC2) 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 EC2 metadatos requiere una implementación de la SdkHttpClient interfaz para el cliente de metadatos sincrónico o la SdkAsyncHttpClient interfaz para el cliente de metadatos asíncrono. HTTPclientesEn la sección se muestra la lista de HTTP clientes 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 EC2 recurso. Por el contrario, es necesario especificar la ruta al EC2 recurso 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

JSONdatos

ActivadoEC2, el Instance Metadata Service (IMDS) que se ejecuta localmente devuelve algunos metadatos como cadenas JSON formateadas. Un ejemplo de ello son los metadatos dinámicos de un documento de identidad de instancias.

La versión 1 API contiene métodos independientes para cada elemento de los metadatos de identidad de la instancia, mientras que la versión 2 devuelve API directamente la JSON cadena. Para trabajar con la JSON cadena, puedes usar el Documento API para analizar la respuesta y navegar por la JSON estructura.

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

En la siguiente tabla se muestran las ubicaciones en las que se SDK comprueba la resolución del punto finalIMDS. 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 final para configurar el cliente de metadatos para que utilice los valores de punto final predeterminados para o. IPv4 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 para. http://[fd00:ec2::254] 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 Ajuste ec2_metadata_service_endpoint IPv4, IPv6 (no distingue entre mayúsculas y minúsculas)
No especificado de las formas anteriores IPv4se utiliza

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

  1. SDKUtiliza el valor que se establece en el código del generador de clientes e ignora cualquier configuración externa. Como se SDK produce una excepción si ambos endpointMode se endpoint invocan en el generador de clientes, SDK utiliza el valor de punto final del método que se utilice.

  2. Si no estableces un valor en el código, 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. La SDK primera comprueba si hay un valor de punto final. Si se encuentra un valor, se usa.

    2. Si SDK aún no ha encontrado ningún valor, SDK busca la configuración del modo de punto final.

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

IMDSv2

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

  • Instance Metadata Service, versión 1 (IMDSv1): enfoque de solicitud/respuesta

  • Instance Metadata Service, versión 2 (IMDSv2): enfoque orientado a la sesión

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

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

La versión 2.x SDK para Java solo es compatible con Java IMDSv2 y no recurre a ella. 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 al pasar un HTTP cliente al método httpClient(...) de creación. El tiempo de espera de conexión predeterminado para HTTP los clientes es de 2 segundos.

Ejemplo de configuración v2 HTTP

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 ApacheHTTP.

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

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