Amazon EC2 インスタンスメタデータを操作する

Amazon EC2 インスタンスメタデータサービスの Java SDK クライアント (メタデータクライアント) を使用すると、アプリケーションはローカル EC2 インスタンスのメタデータにアクセスできます。メタデータクライアントは IMDSv2 のローカルインスタンス (インスタンスメタデータサービス v2) と連携し、セッション指向のリクエストを使用します。

SDK には 2 つのクライアントクラスがあります。同期 Ec2MetadataClient はブロッッキングオペレーション用で、Ec2MetadataAsyncClient は非同期、ノンブロッキングのユースケース用です。

開始方法

メタデータクライアントを使用するには、imds Maven アーティファクトをプロジェクトに追加します。クラスパスには SdkHttpClient (または非同期バリアントの場合は SdkAsyncHttpClient) のクラスも必要です。

次の Maven XML は、同期 UrlConnectionHttpClient を使用するための依存関係のスニペットと、メタデータクライアントの依存関係を示しています。

<dependencyManagement>
   <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>VERSION</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>url-connection-client</artifactId>
    </dependency>
    <!-- other dependencies --> 
</dependencies>

Maven central リポジトリで bom アーティファクトの最新バージョンを検索してください。

非同期 HTTP クライアントを使用するには、url-connection-client アーティファクトの依存関係スニペットを置き換えてください。たとえば、次のスニペットでは NettyNioAsyncHttpClient の実装が取り込まれています。

    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>netty-nio-client</artifactId>
    </dependency>

メタデータクライアントを使用する

メタデータクライアントをインスタンス化する

クラスパスに SdkHttpClient インタフェースの実装が 1 つしかない場合は、同期 Ec2MetadataClient のインスタンスをインスタンス化できます。そのためには、以下のスニペットに示すように静的 Ec2MetadataClient#create() メソッドを呼び出します。

Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.

アプリケーションに SdkHttpClient または SdkHttpAsyncClient インターフェースの実装が複数ある場合は、設定可能な HTTP クライアント セクションに示されているように、メタデータクライアントが使用する実装を指定する必要があります。

注記

Amazon S3 などのほとんどのサービスクライアントでは、SDK for Java は SdkHttpClient または SdkHttpAsyncClient インターフェイスの実装を自動的に追加します。メタデータクライアントが同じ実装を使用している場合は、Ec2MetadataClient#create() は問題なく動作します。別の実装が必要な場合は、メタデータクライアントの作成時にその実装を指定する必要があります。

リクエストを送信する

インスタンスメタデータを取得するには、EC2MetadataClient クラスをインスタンス化し、インスタンスメタデータカテゴリを指定するパスパラメータを使用して get メソッドを呼び出します。

次の例では、ami-id キーに関連付けられた値をコンソールに出力します。

Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/ami-id");
System.out.println(response.asString());
client.close(); // Closes the internal resources used by the Ec2MetadataClient class.

パスが無効な場合、get メソッドは例外を投げます。

close 同じクライアントインスタンスを複数のリクエストに再利用し、リソースを解放する必要がなくなったらクライアントを呼び出します。クローズメソッドが呼び出されると、クライアントインスタンスは使用できなくなります。

レスポンスを解析する

EC2 インスタンスメタデータはさまざまな形式で出力できます。プレーンテキストと JSON が最も一般的に使用される形式です。メタデータクライアントには、これらの形式を処理する方法が用意されています。

次の例に示すように、asString メソッドを使用してデータを Java 文字列として取得します。asList メソッドを使用して、複数行を返すプレーンテキストレスポンスを区切ることもできます。

Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List<String> splits = response.asList();

レスポンスが JSON の場合は、次のコードスニペットに示すように、Ec2MetadataResponse#asDocument メソッドを使用して JSON レスポンスを解析してドキュメントインスタンスにします。

Document fullResponse = response.asDocument();

メタデータの形式が JSON でない場合は例外が発生します。レスポンスが正常に解析されたら、ドキュメント API を使用してレスポンスをより詳細に調べることができます。JSON 形式のレスポンスを返すメタデータカテゴリについては、インスタンスの「metadata category chart」を参照してください。

メタデータクライアントを設定する

再試行

メタデータクライアントには再試行メカニズムを設定できます。そうすることで、クライアントは予期しない理由で失敗したリクエストを自動的に再試行できます。デフォルトでは、クライアントは失敗したリクエストに対し、エクスポネンシャルバックオフ時間を置いて 3 回再試行します。

ユースケースで別の再試行メカニズムが必要な場合は、ビルダーの retryPolicy メソッドを使用してクライアントをカスタマイズできます。たとえば、次の例は、試行間隔が 2 秒、再試行が 5 回になるように設定された同期クライアントを示しています。

BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
                                                                           .backoffStrategy(fixedBackoffStrategy))
                     .build();

メタデータクライアントで使用できる BackoffStrategies はいくつかあります。

次のスニペットに示すように、リトライメカニズムを完全に無効にすることもできます。

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                    .retryPolicy(Ec2MetadataRetryPolicy.none())
                    .build();

Ec2MetadataRetryPolicy#none() を使用すると、メタデータクライアントが再試行しないように、デフォルトの再試行ポリシーが無効になります。

IP バージョン

デフォルトでは、メタデータクライアントは http://169.254.169.254 の IPV4 エンドポイントを使用します。IPV6 バージョンを使用するようにクライアントを変更するには、ビルダーの endpointMode または endpoint メソッドを使用します。ビルダーで両方のメソッドが呼び出されると、例外が発生します。

次の例は、両方の IPV6 オプションを示しています。

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .endpointMode(EndpointMode.IPV6)
                     .build();

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .endpoint(URI.create("http://[fd00:ec2::254]"))
                     .build();

主な特徴

非同期クライアント

ノンブロッキングバージョンのクライアントを使用するには、Ec2MetadataAsyncClient クラスのインスタンスをインスタンス化します。次の例のコードは、デフォルト設定で非同期クライアントを作成し、get メソッドを使用して ami-id キーの値を取得します。

Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture<Ec2MetadataResponse> response = asyncClient.get("/latest/meta-data/ami-id");

get メソッドから返された java.util.concurrent.CompletableFuture は、レスポンスが返された時点で完了します。次の例では、ami-id メタデータをコンソールに出力します。

response.thenAccept(metadata -> System.out.println(metadata.asString()));

設定可能な HTTP クライアント

各メタデータクライアントのビルダーには、カスタマイズされた HTTP クライアントを提供するために使用できる httpClient メソッドがあります。

次の例はカスタム UrlConnectionHttpClient インスタンスのコードを示しています。

SdkHttpClient httpClient =
    UrlConnectionHttpClient.builder()
                           .socketTimeout(Duration.ofMinutes(5))
                           .proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.example.net:8888"))))
                           .build();
Ec2MetadataClient metaDataClient =
    Ec2MetadataClient.builder()
                     .httpClient(httpClient)
                     .build();
// Use the metaDataClient instance.
metaDataClient.close();   // Close the instance when no longer needed.

次の例は、非同期メタデータクライアントを使用するカスタム NettyNioAsyncHttpClient インスタンスのコードを示しています。

SdkAsyncHttpClient httpAsyncClient = 
    NettyNioAsyncHttpClient.builder()
                           .connectionTimeout(Duration.ofMinutes(5))
                           .maxConcurrency(100)
                           .build();
Ec2MetadataAsyncClient asyncMetaDataClient =
    Ec2MetadataAsyncClient.builder()
                          .httpClient(httpAsyncClient)
                          .build();
// Use the asyncMetaDataClient instance.
asyncMetaDataClient.close();   // Close the instance when no longer needed.

このガイドの HTTP クライアント トピックでは、SDK for Java で使用可能な HTTP クライアントの設定方法について詳しく説明しています。

トークンキャッシュ

メタデータクライアントは IMDSv2 を使用するため、すべてのリクエストはセッションに関連付けられます。セッションは、メタデータクライアントが管理する有効期限のあるトークンによって定義されます。メタデータをリクエストするたびに、トークンは有効期限が切れるまで自動的に再利用されます。

デフォルトでは、トークンは 6 時間 (21,600 秒) 持続します。特定のユースケースで高度な設定が必要でない限り、有効期間をデフォルト値のままにしておくことをお勧めします。

必要に応じて、tokenTtl ビルダーメソッドを使用して期間を設定します。たとえば、次のスニペットのコードでは、セッション期間が 5 分のクライアントを作成します。

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .tokenTtl(Duration.ofMinutes(5))
                     .build();

ビルダーで tokenTtl メソッドを呼び出さない場合は、代わりにデフォルトの継続時間である 21,600 が使用されます。