EC2 中繼資料公用程式從版本 1 變更為版本 2 - AWS SDK for Java 2.x
高階變更行為改變配置差異

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

EC2 中繼資料公用程式從版本 1 變更為版本 2

本主題詳述適用於 Java Amazon Elastic Compute Cloud (EC2) 中繼資料公用程式的 SDK 中繼資料公用程式從版本 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 需要實作同步中繼資料用戶端的SdkAsyncHttpClient介面，或非同步中繼資料用戶端的介面。SdkHttpClient此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(...)
環境變數：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系統屬性和組態檔案ec2_metadata_service_endpoint設定 (如果存在) 會被忽略。

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

端點模式

使用 v2，您可以指定端點模式，將中繼資料用戶端設定為使用 IPv4 或 IPv6 的預設端點值。端點模式不適用於 v1。用於 IPv4 的預設值是 IPv6 http://[fd00:ec2::254] 的http://169.254.169.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

SDK 如何解析endpoint或endpoint-mode在 v2 中

  1. SDK 會使用您在用戶端產生器的程式碼中設定的值，並忽略任何外部設定。由於 SDK 會在用戶端建置器上呼叫 endpoint AND endpointMode 時擲回例外狀況，因此 SDK 會使用您使用的任何方法的端點值。

  2. 如果您沒有在程式碼中設定值，SDK 會先查看外部設定，首先是系統屬性，然後是組態檔案中的設定。

    1. SDK 會先檢查端點值。如果找到一個值，則使用它。

    2. 如果 SDK 仍未找到值，SDK 會尋找端點模式設定。

  3. 最後，如果 SDK 找不到外部設定，且您尚未在程式碼中設定中繼資料用戶端，則 SDK 會使用的 http://169.254.169.254 IPv4 值。

IMDSV2

Amazon EC2 定義了兩種存取執行個體中繼資料的方法：

  • 執行個體中繼資料服務第 1 版 (IMDSv1) — 要求/回應方法

  • 執行個體中繼資料服務版本 2 (IMDSv2) — 工作階段導向方法

下表比較 Java 開發套件如何與 IMDS 搭配使用。

v1 v2
依預設會使用 IMDSv2 一律使用
嘗試為每個請求獲取會話令牌，並在無法獲取會話令牌時退回 IMDSv1 將會話令牌保留在用於多個請求的內部緩存中

適用於 Java 2.x 的開發套件僅支援 IMDSv2，而且不會退回至 IMDSv1。

配置差異

下表列出不同的組態選項。

組態 v1 v2
重試 無法使用組態 通過構建器方法配置 retryPolicy(...)
HTTP 可透過AWS_METADATA_SERVICE_TIMEOUT環境變數設定連線逾時。預設值為 1 秒。 通過將 HTTP 客戶端傳遞給構建器方法來實現配置httpClient(...)。HTTP 用戶端的預設連線逾時為 2 秒。

第 2 版 HTTP 組態範例

下列範例顯示如何設定中繼資料用戶端。此範例會設定連線逾時，並使用 Apache HTTP 用戶端。

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

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