As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Trabalhar com metadados da instância do Amazon EC2
Um cliente Java SDK para o Amazon EC2 Instance Metadata Service (cliente de metadados) permite que seus aplicativos acessem metadados em sua instância EC2 local. O cliente de metadados trabalha com a instância local do IMDSv2 (Instance Metadata Service v2) e usa solicitações orientadas à sessão.
Duas classes de cliente estão disponíveis no SDK. O Ec2MetadataClient síncrono serve para operações de bloqueio e o Ec2MetadataAsyncClient
Conceitos básicos
Para usar o cliente de metadados, adicione o artefato imds Maven ao seu projeto. Você também precisa de classes para um SdkHttpClient (ou um SdkAsyncHttpClient para a variante assíncrona) no caminho de classe.
O XML do Maven a seguir mostra trechos de dependência para usar o 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>
Pesquise no repositório central do Mavenbom.
Para usar um cliente HTTP assíncrono, substitua o trecho de dependência do artefato url-connection-client. Por exemplo, o trecho a seguir traz a implementação do NettynioAsynchttpClient
<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>netty-nio-client</artifactId> </dependency>
Usar o cliente de metadados
Instanciar um cliente de metadados
Você pode instanciar uma instância de um Ec2MetadataClient síncrono quando somente uma implementação da interface SdkHttpClient está presente no caminho de classe. Para fazer isso, chame o método estático Ec2MetadataClient#create(), conforme mostrado no trecho a seguir.
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
Se seu aplicativo tiver várias implementações da interface SdkHttpClient ou SdkHttpAsyncClient, você deverá especificar uma implementação para o cliente de metadados usar, conforme mostrado na seção Cliente HTTP configurável.
nota
Para a maioria dos clientes de serviços, como o Amazon S3, o SDK for Java adiciona automaticamente implementações da interface SdkHttpClient ou SdkHttpAsyncClient. Se seu cliente de metadados usar a mesma implementação, o Ec2MetadataClient#create() funcionará. Se você precisar de uma implementação diferente, deverá especificá-la ao criar o cliente de metadados.
Envie solicitações
Para recuperar os metadados da instância, instancie a classe EC2MetadataClient e chame o método get com um parâmetro de caminho que especifica a categoria de metadados da instância.
O exemplo a seguir imprime o valor associado à chave ami-id no 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.
Se o caminho não for válido, o método get gerará uma exceção.
Reutilize a mesma instância do cliente para várias solicitações, mas chame close no cliente quando não for mais necessário liberar recursos. Depois que o método de fechamento é chamado, a instância do cliente não pode mais ser usada.
Analisar respostas
Os metadados da instância EC2 podem ser gerados em formatos diferentes. Texto sem formatação e JSON são os formatos mais usados. Os clientes de metadados oferecem formas de trabalhar com esses formatos.
Como mostra o exemplo a seguir, use o método asString para obter os dados como uma string Java. Você também pode usar o método asList para separar uma resposta de texto sem formatação que retorna várias linhas.
Ec2MetadataClient client = Ec2MetadataClient.create(); Ec2MetadataResponse response = client.get("/latest/meta-data/"); String fullResponse = response.asString(); List<String> splits = response.asList();
Se a resposta estiver em JSON, use o método Ec2MetadataResponse#asDocument para analisar a resposta JSON em uma instância de Documento
Document fullResponse = response.asDocument();
Uma exceção será lançada se o formato dos metadados não estiver em JSON. Se a resposta for analisada com sucesso, você poderá usar a API do documento
Configurar um cliente de metadados
Tentativas
Você pode configurar um cliente de metadados com um mecanismo de repetição. Se você fizer isso, o cliente poderá repetir automaticamente as solicitações que falharem por motivos inesperados. Por padrão, o cliente tenta novamente três vezes em uma solicitação com falha, com um tempo de recuo exponencial entre as tentativas.
Se seu caso de uso exigir um mecanismo de repetição diferente, você poderá personalizar o cliente usando o método retryPolicy em seu construtor. Por exemplo, o exemplo a seguir mostra um cliente síncrono configurado com um atraso fixo de dois segundos entre as tentativas e cinco tentativas de repetição.
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2)); Ec2MetadataClient client = Ec2MetadataClient.builder() .retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5) .backoffStrategy(fixedBackoffStrategy)) .build();
Existem várias BackoffStrategies
Você também pode desativar totalmente o mecanismo de repetição, como mostra o trecho a seguir.
Ec2MetadataClient client = Ec2MetadataClient.builder() .retryPolicy(Ec2MetadataRetryPolicy.none()) .build();
O uso do Ec2MetadataRetryPolicy#none() desativa a política de repetição padrão para que o cliente de metadados não tente fazer novas tentativas.
Versão de IP
Por padrão, um cliente de metadados usa o endpoint IPV4 em http://169.254.169.254. Para alterar o cliente para usar a versão IPV6, use o método endpointMode ou endpoint do construtor. Uma exceção ocorre se os dois métodos forem chamados no construtor.
Os exemplos a seguir mostram as duas opções de IPV6.
Ec2MetadataClient client = Ec2MetadataClient.builder() .endpointMode(EndpointMode.IPV6) .build();
Ec2MetadataClient client = Ec2MetadataClient.builder() .endpoint(URI.create("http://[fd00:ec2::254]")) .build();
Recursos principais
Cliente assíncrono
Para usar a versão sem bloqueio do cliente, instancie uma instância da classe Ec2MetadataAsyncClient. O código no exemplo a seguir cria um cliente assíncrono com configurações padrão e usa o método get para recuperar o valor da chave ami-id.
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create(); CompletableFuture<Ec2MetadataResponse> response = asyncClient.get("/latest/meta-data/ami-id");
O java.util.concurrent.CompletableFuture retornado pelo método get é concluído quando a resposta retorna. O exemplo a seguir imprime os metadados ami-id no console.
response.thenAccept(metadata -> System.out.println(metadata.asString()));
Cliente HTTP configurável
O construtor de cada cliente de metadados tem um método httpClient que você pode usar para fornecer um cliente HTTP personalizado.
O exemplo a seguir mostra o código para uma instância personalizada do UrlConnectionHttpClient.
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.
O exemplo a seguir mostra o código de uma instância personalizada do NettyNioAsyncHttpClient com um cliente de metadados assí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.
O tópico HTTPclientes deste guia fornece detalhes sobre como configurar os clientes HTTP que estão disponíveis no SDK para Java.
Armazenamento em cache de tokens
Como os clientes de metadados usam o IMDSv2, todas as solicitações são associadas a uma sessão. Uma sessão é definida por um token que tem uma expiração, que o cliente de metadados gerencia para você. Cada solicitação de metadados reutiliza automaticamente o token até que ele expire.
Por padrão, um token dura seis horas (21.600 segundos). Recomendamos que você mantenha o valor de vida útil padrão, a menos que seu caso de uso específico exija configuração avançada.
Se necessário, configure a duração usando o método tokenTtl do construtor. Por exemplo, o código no trecho a seguir cria um cliente com duração de sessão de cinco minutos.
Ec2MetadataClient client = Ec2MetadataClient.builder() .tokenTtl(Duration.ofMinutes(5)) .build();
Se você omitir a chamada do método tokenTtl no construtor, a duração padrão de 21.600 será usada em vez disso.
