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

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

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(...)
环境变量: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。使用的默认值为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 IPv4IPv6(大小写没有影响)
Config 文件:~.aws/config ec2_metadata_service_endpoint 设置 IPv4IPv6(大小写没有影响)
未在前面的方法中指定 IPv4被使用了

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

  1. SDK使用您在客户端生成器的代码中设置的值,并忽略任何外部设置。因为如果在客户端生成器上同时调用endpointendpointMode都会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 连接超时可通过 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();