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.
Trabajar con metadatos de la instancia de Amazon EC2
Un cliente Java SDK para el servicio de metadatos de la instancia de Amazon EC2 (cliente de metadatos) permite a sus aplicaciones acceder a los metadatos de su instancia EC2 local. El cliente de metadatos trabaja con la instancia local de IMDSv2 (Instance Metadata Service v2) y utiliza peticiones orientadas a la sesión.
Hay dos clases de clientes disponibles en el SDK. El síncrono Ec2MetadataClient es para operaciones de bloqueo, y el Ec2MetadataAsyncClient
Introducción
Para usar el cliente de metadatos, agregue el artefacto Maven imds a su proyecto. También necesita clases para una SdkHttpClient (o una SdkAsyncHttpClient para la variante asíncrona) de la ruta de clases.
El siguiente XML de Maven muestra fragmentos de dependencia para utilizar el UrlConnectionHttpClient
<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>
Busca en el repositorio central de Mavenbom.
Para usar un cliente HTTP asíncrono, sustituya el fragmento de dependencia del artefacto url-connection-client. Por ejemplo, el siguiente fragmento de código incluye la implementación NettyNioAsyncHttpClient
<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>netty-nio-client</artifactId> </dependency>
Utilizar el cliente de metadatos
Crear una instancia de un cliente de metadatos
Puede crear una instancia de un sistema síncrono Ec2MetadataClient cuando solo haya una implementación de la interfaz SdkHttpClient en la ruta de clases. Para ello, llame al método estático Ec2MetadataClient#create(), como se muestra en el siguiente fragmento de código.
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
Si su aplicación tiene varias implementaciones de la interfaz SdkHttpClient o SdkHttpAsyncClient, debe especificar una implementación para que la utilice el cliente de metadatos, como se muestra en la sección Cliente HTTP configurable.
nota
Para la mayoría de los clientes de servicios, como Amazon S3, el SDK para Java añade automáticamente las implementaciones de la interfaz SdkHttpClient o SdkHttpAsyncClient. Si su cliente de metadatos usa la misma implementación, Ec2MetadataClient#create() funcionará. Si necesita una implementación diferente, debe especificarla al crear el cliente de metadatos.
Enviar solicitudes
Para recuperar metadatos de la instancia, instancie la clase EC2MetadataClient y llame al método get con un parámetro de ruta que especifique la categoría de metadatos de la instancia.
En el siguiente ejemplo, se imprime el valor asociado a la clave ami-id de la consola.
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 la ruta no es válida, el método get genera una excepción.
Puede reutilizar la misma instancia de cliente para varias solicitudes, pero ejecute close en el cliente cuando ya no sea necesario, con el fin de liberar recursos. Después de llamar al método close, la instancia de cliente ya no se puede usar.
Analizar las respuestas
Los metadatos de la instancia EC2 se pueden generar en diferentes formatos. Los más utilizados son el texto sin formato y JSON. Los clientes de metadatos ofrecen formas de trabajar con esos formatos.
Como se muestra en el ejemplo siguiente, utilice el método asString para obtener los datos como una cadena Java. También puede usar el método asList para separar una respuesta de texto sin formato que devuelva varias líneas.
Ec2MetadataClient client = Ec2MetadataClient.create(); Ec2MetadataResponse response = client.get("/latest/meta-data/"); String fullResponse = response.asString(); List<String> splits = response.asList();
Si la respuesta está en JSON, use el método Ec2MetadataResponse#asDocument para analizarla y convertirla en una instancia de Document
Document fullResponse = response.asDocument();
Si el formato de los metadatos no está en JSON, se producirá una excepción. Si la respuesta se ha analizado correctamente, puede utilizar la API de documentos
Configurar un cliente de metadatos
Reintentos
Puede configurar un cliente de metadatos con un mecanismo de reintento. Si lo hace, el cliente podrá reintentar automáticamente las solicitudes que no puedan completarse por motivos inesperados. De forma predeterminada, el cliente lo vuelve a intentar tres veces en caso de una solicitud fallida, con un tiempo de retroceso exponencial entre intentos.
Si su caso de uso requiere un mecanismo de reintento diferente, puede personalizar el cliente mediante el método retryPolicy de su generador. Por ejemplo, el siguiente ejemplo muestra un cliente síncrono configurado con un retraso fijo de dos segundos entre intentos y cinco reintentos.
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2)); Ec2MetadataClient client = Ec2MetadataClient.builder() .retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5) .backoffStrategy(fixedBackoffStrategy)) .build();
Hay varias BackoffStrategies
También puede inhabilitar por completo el mecanismo de reintento, como se muestra en el siguiente fragmento de código.
Ec2MetadataClient client = Ec2MetadataClient.builder() .retryPolicy(Ec2MetadataRetryPolicy.none()) .build();
El uso de Ec2MetadataRetryPolicy#none() desactiva la política de reintentos predeterminada para que el cliente de metadatos no efectúe reintentos.
Versión de IP
De forma predeterminada, un cliente de metadatos usa el punto de conexión IPV4 en http://169.254.169.254. Para que el cliente utilice la versión IPV6, utilice el método endpointMode o endpoint del constructor. Si se llaman ambos métodos en el constructor se produce una excepción.
Los ejemplos siguientes muestran ambas opciones de IPV6.
Ec2MetadataClient client = Ec2MetadataClient.builder() .endpointMode(EndpointMode.IPV6) .build();
Ec2MetadataClient client = Ec2MetadataClient.builder() .endpoint(URI.create("http://[fd00:ec2::254]")) .build();
Características principales
Cliente asíncrono
Para utilizar la versión no bloqueante del cliente, instancie una instancia de la clase Ec2MetadataAsyncClient. El código del siguiente ejemplo crea un cliente asíncrono con la configuración predeterminada y utiliza el método get para recuperar el valor de la clave ami-id.
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create(); CompletableFuture<Ec2MetadataResponse> response = asyncClient.get("/latest/meta-data/ami-id");
El valor de java.util.concurrent.CompletableFuture devuelto por el método get se completa cuando se devuelve la respuesta. En el ejemplo siguiente, se imprimen los metadatos ami-id en la consola.
response.thenAccept(metadata -> System.out.println(metadata.asString()));
Cliente HTTP configurable
El generador de cada cliente de metadatos tiene un método httpClient que puede utilizar para proporcionar un cliente HTTP personalizado.
El ejemplo siguiente muestra el código para una instancia UrlConnectionHttpClient personalizada.
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.
En el ejemplo siguiente, se muestra el código de una instancia NettyNioAsyncHttpClient personalizada con un cliente de metadatos asíncrono.
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.
El tema HTTPclientes de esta guía proporciona detalles sobre cómo configurar los clientes de HTTP disponibles en el SDK para Java.
Almacenamiento en caché de tokens
Como los clientes de metadatos utilizan IMDSv2, todas las solicitudes están asociadas a una sesión. Una sesión se define mediante un token que tiene una caducidad, que el cliente de metadatos administra en su lugar. Cada solicitud de metadatos reutiliza automáticamente el token hasta que caduque.
De forma predeterminada, un token dura seis horas (21 600 segundos). Le recomendamos que mantenga el valor predeterminado de tiempo de vida, a menos que su caso práctico específico requiera una configuración avanzada.
Si es necesario, configure la duración utilizando el método de generador tokenTtl. Por ejemplo, el código del siguiente fragmento crea un cliente con una duración de sesión de cinco minutos.
Ec2MetadataClient client = Ec2MetadataClient.builder() .tokenTtl(Duration.ofMinutes(5)) .build();
Si omite llamar al método tokenTtl en el generador, se utilizará en su lugar la duración predeterminada de 21 600.
