EC2 メタデータユーティリティのバージョン 1 からバージョン 2 への変更 - AWS SDK for Java 2.x
高レベル変更動作の変更設定の違い

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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 形式の文字列として返します。その一例が、インスタンス ID ドキュメントの動的メタデータです。

v1 API にはインスタンス ID メタデータごとに個別のメソッドが含まれていますが、v2 API は JSON 文字列を直接返します。JSON 文字列を処理するには、ドキュメント API を使用して応答を解析し、JSON 構造に移動します。

次の表は、v1 と v2 でインスタンス ID ドキュメントのメタデータを取得する方法を比較したものです。

ユースケース 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();

エンドポイント解決の違い

次の表は、エンドポイントを IMDS に対して解決するために SDK がチェックする場所を示しています。場所は優先度の高い順にリストされています。

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 で使用されるデフォルト値は 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 (大文字と小文字は区別されません)
設定ファイル: ~.aws/config ec2_metadata_service_endpoint の設定 IPv4、IPv6 (大文字と小文字は区別されません)
以前の方法では未指定 IPv4 が使用される

v2 での SDK による endpoint または endpoint-mode の解決方法

  1. SDK は、クライアントビルダーのコードで設定した値を使用し、外部設定は無視します。endpoint および endpointMode が両方ともクライアントビルダーで呼び出されると SDK は例外をスローするため、SDK はユーザーが使用するメソッドのエンドポイント値を使用します。

  2. コードで値を設定しない場合、SDK は外部設定を調べます。最初にシステムプロパティを検索し、次に設定ファイル内の設定を検索します。

    1. SDK は最初にエンドポイント値をチェックします。値が見つかると、その値が使用されます。

    2. 値が見つからない場合は、SDK はエンドポイントモード設定を探します。

  3. 最後に、SDK が外部設定を見つけられず、コードでメタデータクライアントを設定していない場合は、SDK は IPv4 の値の http://169.254.169.254 を使用します。

IMDSv2

Amazon EC2 では、インスタンスメタデータにアクセスするための 2 つのアプローチを定義しています。

  • インスタンスメタデータサービスバージョン 1 (IMDSv1) – リクエスト/レスポンスアプローチ

  • インスタンスメタデータサービスバージョン 2 (IMDSv2) – セッション指向アプローチ

次の表は、Java SDK が IMDS をどのように使用するかを比較したものです。

v1 v2
IMDSv2 がデフォルトで使用される IMDSv2 を常に使用する
リクエストごとにセッショントークンの取得を試み、セッショントークンの取得に失敗した場合は IMDSv1 にフォールバックする セッショントークンを内部キャッシュに保持し、複数のリクエストで再利用する

SDK for Java 2.x は IMDSv2 のみをサポートしており、IMDSv1 にはフォールバックしません。

設定の違い

以下の表にさまざまな設定オプション一覧表示します。

構成 v1 v2
再試行 設定不可 ビルダーメソッド retryPolicy(...) で設定可能
HTTP 接続タイムアウトは AWS_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();