本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
EC2元数据实用程序从版本 1 到版本 2 的更改
本主题详细介绍了SDK适用于 Java 的 Amazon Elastic Compute Cloud (EC2) 元数据实用程序从版本 1 (v1) 到版本 2 (v2) 的变化。
高级别更改
更改 | v1 | v2 |
---|---|---|
Maven 依赖项 |
|
|
软件包名称 |
com.amazonaws.util |
software.amazon.awssdk.imds |
实例化方法 |
使用静态实用程序方法;不进行实例化:
|
使用静态工厂方法:
或者使用生成器方法:
|
客户端类型 | 仅同步实用程序方法:EC2MetadataUtils |
同步: 异步: |
3 注意 v2 的 apache-client
模块声明。EC2元数据实用程序的 V2 需要实现同步元数据客户端的SdkHttpClient
接口或异步元数据客户端的SdkAsyncHttpClient
接口。该HTTP客户部分显示了您可以使用的HTTP客户端列表。
请求元数据
在 v1 中,您可以使用不接受任何参数的静态方法来请求EC2资源的元数据。相比之下,您需要在 v2 中将EC2资源路径指定为参数。下表显示了不同的方法。
v1 | v2 |
---|---|
|
|
请参阅实例元数据类别,查找请求元数据时需要提供的路径。
注意
在 v2 中使用实例元数据客户端时,您应该针对检索元数据的所有请求使用同一客户端。
行为更改
JSON数据
开启后EC2,本地运行的实例元数据服务 (IMDS) 以JSON格式化字符串的形式返回一些元数据。实例身份文档的动态元数据就是一个例子。
v1 为每段实例身份元数据API包含不同的方法,而 v2 则API直接返回字符串。JSON要使用JSON字符串,可以使用 D ocumen
下表比较了在 v1 和 v2 中检索实例身份文档元数据的方式。
应用场景 | v1 | v2 |
---|---|---|
检索区域 |
|
|
检索实例 ID |
|
|
检索实例类型 |
|
|
端点解析差异
下表显示了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(...) |
|
EndpointMode.IPV4 ,
EndpointMode.IPV6 |
系统属性 | aws.ec2MetadataServiceEndpointMode |
IPv4 、IPv6 (大小写没有影响) |
Config 文件:~.aws/config |
ec2_metadata_service_endpoint 设置 |
IPv4 、IPv6 (大小写没有影响) |
未在前面的方法中指定 | IPv4被使用了 |
在 v2 中是如何SDK解析endpoint
endpoint-mode
的
-
SDK使用您在客户端生成器的代码中设置的值,并忽略任何外部设置。因为如果在客户端生成器上同时调用
endpoint
和endpointMode
都会SDK引发异常,因此无论使用哪种方法,都SDK使用来自任何方法的端点值。 -
如果您没有在代码中设置值,则会SDK查看外部配置,首先是系统属性,然后是配置文件中的设置。
-
SDK第一个检查端点值。如果找到值,则使用该值。
-
如果SDK仍未找到值,则会SDK查找端点模式设置。
-
-
最后,如果未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();