Alterações no utilitário de metadados do EC2 da versão 1 para a versão 2 - AWS SDK for Java 2.x
Alterações de alto nívelAlteração de comportamentoDiferenças de configuração

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

Alterações no utilitário de metadados do EC2 da versão 1 para a versão 2

Este tópico detalha as alterações no utilitário de metadados Amazon Elastic Compute Cloud (EC2) do SDK para Java da versão 1 (v1) para a versão 2 (v2).

Alterações de alto nível

Alteração v1 v2

Dependências do 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 do pacote com.amazonaws.util software.amazon.awssdk.imds
Abordagem de instanciação

Use métodos de utilitário estático; sem instanciação:

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

Use um método estático de fábrica:

Ec2MetadataClient client = Ec2MetadataClient.create();

Ou use uma abordagem de criador:

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();
Tipos de clientes Somente métodos de utilitário síncronos: EC2MetadataUtils

Síncrono: Ec2MetadataClient

Assíncrono: Ec2MetadataAsyncClient

1 Versão mais recente. 2 Versão mais recente.

3 Observe a declaração do módulo apache-client para v2. A V2 do utilitário de metadados do EC2 requer uma implementação da interface SdkHttpClient para o cliente de metadados síncronos ou da interface SdkAsyncHttpClient para o cliente de metadados assíncronos. A seção Clientes HTTP mostra a lista de clientes HTTP que você pode usar.

Solicitar metadados

Na v1, você deve usar métodos estáticos que não aceitem parâmetros para solicitar metadados para um recurso do EC2. Por outro lado, é necessário especificar o caminho para o recurso do EC2 como um parâmetro na v2. A tabela a seguir mostra as diferentes abordagens.

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

Consulte as categorias de metadados da instância para encontrar o caminho que você precisa fornecer para solicitar uma parte dos metadados.

nota

Ao usar um cliente de metadados de instância na v2, é necessário usar o mesmo cliente para todas as solicitações para recuperação de metadados.

Alteração de comportamento

Dados JSON

No EC2, o serviço de metadados de instância (IMDS) em execução local exibe alguns metadados como strings formatadas em JSON. Um exemplo são os metadados dinâmicos de um documento de identidade de instância.

A API da v1 contém métodos separados para cada parte dos metadados de identidade da instância, enquanto a API da v2 exibe diretamente a string JSON. Para trabalhar com a string JSON, é possível usar a API de documento para analisar a resposta e navegar pela estrutura JSON.

A tabela a seguir compara como recuperar metadados de um documento de identidade de instância na v1 e na v2.

Caso de uso v1 v2
Recuperar a região 
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();
Recupere o ID da instância 
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();
Recupere o tipo da instância 
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();

Diferenças na resolução do endpoint

A tabela a seguir mostra os locais que o SDK confere para resolver o endpoint para o IMDS. Os locais são listados em ordem decrescente em termos de prioridade.

v1 v2
Propriedade do sistema: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride Método de configuração do criador do cliente: endpoint(...)
Variável de ambiente: AWS_EC2_METADATA_SERVICE_ENDPOINT Propriedade do sistema: aws.ec2MetadataServiceEndpoint
Valor padrão: http://169.254.169.254 Arquivo de configuração: ~.aws/config com a configuração ec2_metadata_service_endpoint
Valor associado ao endpoint-mode resolvido
Valor padrão: http://169.254.169.254

Resolução de endpoint na v2

Quando você define explicitamente um endpoint usando o criador, esse valor de endpoint tem prioridade sobre todas as outras configurações. Quando o código a seguir é executado, a propriedade do sistema aws.ec2MetadataServiceEndpoint e a definição do arquivo de configuração ec2_metadata_service_endpoint serão ignoradas, se existirem.

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

Modo de endpoint

Com a v2, é possível especificar um modo de endpoint para configurar o cliente de metadados para usar os valores de endpoint padrão para IPv4 ou IPv6. O modo de endpoint não está disponível para a v1. O valor padrão usado para IPv4 é http://169.254.169.254 e http://[fd00:ec2::254] para IPv6.

A tabela a seguir mostra as diferentes maneiras pelas quais é possível definir o modo de endpoint em ordem decrescente em termos de prioridade.

Possíveis valores
Método de configuração do criador do cliente: endpointMode(...) 
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();
 EndpointMode.IPV4, EndpointMode.IPV6
Propriedades do sistema aws.ec2MetadataServiceEndpointMode IPv4, IPv6 (o uso de maiúsculas ou minúsculas não importa)
Arquivo de configuração: ~.aws/config Configuração da ec2_metadata_service_endpoint IPv4, IPv6 (o uso de maiúsculas ou minúsculas não importa)
Não especificado nas formas anteriores O IPv4 é usado

Como o SDK resolve endpoint ou endpoint-mode na v2

  1. O SDK usa o valor definido no código no criador do cliente e ignora todas as configurações externas. Como o SDK vai gerar uma exceção se endpoint e endpointMode forem chamados no criador do cliente, o SDK usará o valor do endpoint de qualquer método usado.

  2. Se você não definir um valor no código, o SDK examinará a configuração externa: primeiro as propriedades do sistema e depois uma configuração no arquivo de configuração.

    1. O SDK primeiro confere o valor de um endpoint. Se um valor for encontrado, ele será usado.

    2. Se o SDK ainda não encontrou um valor, ele procurará as configurações do modo de endpoint.

  3. Por fim, se o SDK não encontrar configurações externas e você não tiver configurado o cliente de metadados no código, o SDK usará o valor IPv4 de http://169.254.169.254.

IMDSv2

O Amazon EC2 define duas abordagens para acessar os metadados da instância:

  • O serviço de metadados de instância versão 1 (IMDSv1): uma abordagem de solicitação/resposta

  • Serviço de metadados de instância versão 2 (IMDSv2): uma abordagem orientada a sessões

A tabela a seguir compara como os SDKs do Java funcionam com o IMDS.

v1 v2
O IMDSv2 é usado por padrão Sempre usa o IMDSv2
Tenta buscar um token de sessão para cada solicitação e voltará para o IMDSv1 se não conseguir receber um token de sessão. Mantém um token de sessão em um cache interno que é reutilizado para várias solicitações.

O SDK para Java 2.x é compatível somente com o IMDSv2 e não retorna ao IMDSv1.

Diferenças de configuração

A tabela a seguir lista as diferentes opções de configuração.

Configuração v1 v2
Repetições Configuração não disponível Configurável por meio do método do criador retryPolicy(...)
HTTP Tempo limite de conexão configurável por meio da variável de ambiente AWS_METADATA_SERVICE_TIMEOUT. O padrão é 1 segundo. Configuração disponível ao transmitir um cliente HTTP para o método do criador httpClient(...). O tempo limite de conexão padrão para clientes HTTP é de 2 segundos.

Exemplo de configuração de HTTP v2

O exemplo a seguir mostra como configurar o cliente de metadados. Este exemplo configura o tempo limite de conexão e usa o cliente do Apache HTTP.

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

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