EC2 元数据实用程序从版本 1 到版本 2 的变化 - Amazon SDK for Java 2.x
高级别更改行为更改配置差异
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

EC2 元数据实用程序从版本 1 到版本 2 的变化

本主题详细介绍了 SDK for 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.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>
软件包名称 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 字符串，您可以使用文档 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(...)
环境变量：Amazon_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。用于 IPv4 的默认值为 http://169.254.169.254，对于 IPv6，则为 http://[fd00:ec2::254]。

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

可能的值
客户端生成器配置方法：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 如何解析endpoint或endpoint-mode

  1. SDK 使用您通过客户端生成器在代码中设置的值，并忽略任何外部设置。由于在客户端生成器上同时调用 endpoint 和 endpointMode 时，SDK 会抛出异常，因此 SDK 将使用您所用的任一方法中的端点值。

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

    1. SDK 会先检查端点值。如果找到值，则使用该值。

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

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

IMDSv2

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

  • 实例元数据服务版本 1（IMDSv1）：请求/响应方法

  • 实例元数据服务版本 2（IMDSv2）：面向会话的方法

下表比较了 Java SDK 与 IMDS 协同工作的方式。

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

SDK for Java 2.x 仅支持 IMDSv2，不会回退到 IMDSv1。

配置差异

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

配置 v1 v2
重试 配置不可用 可通过生成器方法 retryPolicy(...) 配置
HTTP 连接超时可通过 Amazon_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();