EC2元数据实用程序从版本 1 到版本 2 的更改 - AWS SDK for Java 2.x
高级别更改行为更改配置差异

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

EC2元数据实用程序从版本 1 到版本 2 的更改

本主题详细介绍了SDK适用于 Java 的 Amazon Elastic Compute Cloud (EC2) 元数据实用程序从版本 1 (v1) 到版本 2 (v2) 的变化。

高级别更改

更改 v1 v2

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>
软件包名称 com.amazonaws.util software.amazon.awssdk.imds
实例化方法

使用静态实用程序方法；不进行实例化：

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

使用静态工厂方法：

Ec2MetadataClient client = Ec2MetadataClient.create();

或者使用生成器方法：

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();
客户端类型 仅同步实用程序方法：EC2MetadataUtils

同步：Ec2MetadataClient

异步：Ec2MetadataAsyncClient

1 最新版本。2 最新版本。

3 注意 v2 的 apache-client 模块声明。EC2元数据实用程序的 V2 需要实现同步元数据客户端的SdkHttpClient接口或异步元数据客户端的SdkAsyncHttpClient接口。该HTTP客户部分显示了您可以使用的HTTP客户端列表。

请求元数据

在 v1 中，您可以使用不接受任何参数的静态方法来请求EC2资源的元数据。相比之下，您需要在 v2 中将EC2资源路径指定为参数。下表显示了不同的方法。

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

请参阅实例元数据类别，查找请求元数据时需要提供的路径。

注意

在 v2 中使用实例元数据客户端时，您应该针对检索元数据的所有请求使用同一客户端。

行为更改

JSON数据

开启后EC2，本地运行的实例元数据服务 (IMDS) 以JSON格式化字符串的形式返回一些元数据。实例身份文档的动态元数据就是一个例子。

v1 为每段实例身份元数据API包含不同的方法，而 v2 则API直接返回字符串。JSON要使用JSON字符串，可以使用 D ocumen t API 来解析响应并浏览JSON结构。

下表比较了在 v1 和 v2 中检索实例身份文档元数据的方式。

应用场景 v1 v2
检索区域 
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();
检索实例 ID 
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();
检索实例类型 
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();

端点解析差异

下表显示了SDK通过检查将端点解析到的位置IMDS。这些位置按优先级降序列出。

v1 v2
系统属性：com.amazonaws.sdk.ec2MetadataServiceEndpointOverride 客户端生成器配置方法：endpoint(...)
环境变量：AWS_EC2_METADATA_SERVICE_ENDPOINT 系统属性：aws.ec2MetadataServiceEndpoint
默认值：http://169.254.169.254 Config 文件：~.aws/config，及 ec2_metadata_service_endpoint 设置
与已解析的 endpoint-mode 相关联的值
默认值：http://169.254.169.254

v2 中的端点解析

如果您使用生成器显式设置端点，该端点值的优先级高于所有其他设置。当以下代码执行时，aws.ec2MetadataServiceEndpoint 系统属性和 config 文件 ec2_metadata_service_endpoint 设置如果存在，将被忽略。

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

端点模式

在 v2 中，您可以指定端点模式，将元数据客户端配置为使用或的默认端点值。IPv4 IPv6端点模式不适用于 v1。使用的默认值为http://169.254.169.254和 IPv4 fo http://[fd00:ec2::254] r IPv6。

下表按优先级降序显示了设置端点模式时可以采用的不同方法。

可能的值
客户端生成器配置方法：endpointMode(...) 
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();
 EndpointMode.IPV4, EndpointMode.IPV6
系统属性 aws.ec2MetadataServiceEndpointMode IPv4、IPv6（大小写没有影响）
Config 文件：~.aws/config ec2_metadata_service_endpoint 设置 IPv4、IPv6（大小写没有影响）
未在前面的方法中指定 IPv4被使用了

在 v2 中是如何SDK解析endpointendpoint-mode的

  1. SDK使用您在客户端生成器的代码中设置的值，并忽略任何外部设置。因为如果在客户端生成器上同时调用endpoint和endpointMode都会SDK引发异常，因此无论使用哪种方法，都SDK使用来自任何方法的端点值。

  2. 如果您没有在代码中设置值，则会SDK查看外部配置，首先是系统属性，然后是配置文件中的设置。

    1. SDK第一个检查端点值。如果找到值，则使用该值。

    2. 如果SDK仍未找到值，则会SDK查找端点模式设置。

  3. 最后，如果未SDK找到任何外部设置，并且您尚未在代码中配置元数据客户端，则SDK使用IPv4值http://169.254.169.254。

IMDSv2

Amazon EC2 定义了两种访问实例元数据的方法：

  • 实例元数据服务版本 1 (IMDSv1)-请求/响应方法

  • 实例元数据服务版本 2 (IMDSv2)-面向会话的方法

下表比较了 Java SDKs 的工作原理IMDS。

v1 v2
IMDSv2默认情况下使用 始终使用 IMDSv2
尝试为每个请求获取会话令牌，IMDSv1如果无法获取会话令牌，则回退到会话令牌 将会话令牌保存在内部缓存中，该令牌可重复用于多个请求

SDK适用于 Java 2.x 的 2.x 仅支持IMDSv2，不能回退到。IMDSv1

配置差异

下表列出了不同的配置选项。

配置 v1 v2
重试 配置不可用 可通过生成器方法 retryPolicy(...) 配置
HTTP 连接超时可通过 AWS_METADATA_SERVICE_TIMEOUT 环境变量配置。默认值为 1 秒。 通过将HTTP客户端传递给生成器方法即可进行配置httpClient(...)。HTTP客户端的默认连接超时为 2 秒。

v2 配置HTTP示例

以下示例演示了如何配置元数据客户端。此示例配置连接超时并使用 Apache HTTP 客户端。

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

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