本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
EC2 中繼資料公用程式從版本 1 變更為版本 2
本主題詳述適用於 Java Amazon Elastic Compute Cloud (EC2) 中繼資料公用程式的 SDK 中繼資料公用程式從版本 1 (v1) 到第 2 版 (v2) 的變更。
高階變更
變更 | v1 | v2 |
---|---|---|
Maven 的依賴 |
|
|
套件名稱 |
com.amazonaws.util |
software.amazon.awssdk.imds |
實例化方法 |
使用靜態實用程序方法; 沒有實例化:
|
使用靜態工廠方法:
或者使用構建器方法:
|
客戶類型 | 僅同步實用程序方法:EC2MetadataUtils |
同步: 非同步: |
3 注意 v2 apache-client
模塊的聲明。EC2 中繼資料公用程式的 V2 需要實作同步中繼資料用戶端的SdkAsyncHttpClient
介面,或非同步中繼資料用戶端的介面。SdkHttpClient
此HTTP客戶段落顯示您可以使用的 HTTP 從屬端清單。
請求元數據
在 v1 中,您使用不接受任何參數的靜態方法來請求 EC2 資源的中繼資料。相比之下,您需要在 v2 中將 EC2 資源的路徑指定為參數。下表顯示了不同的方法。
v1 | v2 |
---|---|
|
|
請參閱執行個體中繼資料類別,找出要求中繼資料時所需提供的路徑。
注意
當您在 v2 中使用實例元數據客戶端時,您應該針對所有請求使用相同的客戶端來檢索元數據。
行為改變
JSON 資料
在 EC2 上,本機執行的執行個體中繼資料服務 (IMDS) 會以 JSON 格式的字串傳回一些中繼資料。其中一個例子就是執行個體身分識別文件的動態中繼資料。
v1 API 為每個實例身份元數據包含單獨的方法,而 v2 API 直接返回 JSON 字符串。若要使用 JSON 字串,您可以使用文件 API
下表比較如何在 v1 和 v2 中擷取執行個體身分識別文件的中繼資料。
使用案例 | v1 | v2 |
---|---|---|
擷取區域 |
|
|
擷取執行個體 ID |
|
|
擷取執行個體類型 |
|
|
端點解析度差異
下表顯示 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(...) |
|
EndpointMode.IPV4 ,
EndpointMode.IPV6 |
系統屬性 | aws.ec2MetadataServiceEndpointMode |
IPv4 ,IPv6 (情況並不重要) |
Config 文件:~.aws/config |
ec2_metadata_service_endpoint 設定 |
IPv4 ,IPv6 (情況並不重要) |
未在以前的方式指定 | 使用 IPv4 |
SDK 如何解析endpoint
或endpoint-mode
在 v2 中
-
SDK 會使用您在用戶端產生器的程式碼中設定的值,並忽略任何外部設定。由於 SDK 會在用戶端建置器上呼叫
endpoint
ANDendpointMode
時擲回例外狀況,因此 SDK 會使用您使用的任何方法的端點值。 -
如果您沒有在程式碼中設定值,SDK 會先查看外部設定,首先是系統屬性,然後是組態檔案中的設定。
-
SDK 會先檢查端點值。如果找到一個值,則使用它。
-
如果 SDK 仍未找到值,SDK 會尋找端點模式設定。
-
-
最後,如果 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();