Bekerja dengan metadata instans Amazon EC2

Klien Java SDK untuk Layanan Metadata Instans Amazon EC2 (klien metadata) memungkinkan aplikasi Anda mengakses metadata pada instans EC2 lokal mereka. Klien metadata bekerja dengan instance lokal IMDSv2 (Instance Metadata Service v2) dan menggunakan permintaan berorientasi sesi.

Dua kelas klien tersedia di SDK. SinkronEc2MetadataClient adalah untuk memblokir operasi, dan Ec2MetadataAsyncClientadalah untuk kasus penggunaan asinkron dan non-pemblokiran.

Memulai

Untuk menggunakan klien metadata, tambahkan artefakimds Maven ke proyek Anda. Anda juga membutuhkan kelas untukSdkHttpClient (atauSdkAsyncHttpClient untuk varian asinkron) pada classpath.

Berikut Maven XMLmenunjukkan potongan ketergantungan untuk menggunakan sinkron UrlConnectionHttpClientbersama dengan ketergantungan untuk klien metadata.

<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>

Cari repositori pusat Maven untuk versi terbaru daribom artefak.

Untuk menggunakan klien HTTP asynchronous, ganti potongan dependensi untukurl-connection-client artefak. Misalnya, cuplikan berikut membawa NettyNioAsyncHttpClientimplementasi.

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

Menggunakan klien metadata

Instantiate klien metadata

Anda dapat instantiate sebuah instance dari sinkronEc2MetadataClient ketika hanya satu implementasiSdkHttpClient antarmuka hadir pada classpath. Untuk melakukannya, panggilEc2MetadataClient#create() metode statis seperti yang ditunjukkan dalam potongan berikut.

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

Jika aplikasi Anda memiliki beberapa implementasiSdkHttpClient atauSdkHttpAsyncClient antarmuka, Anda harus menentukan implementasi untuk metadata klien untuk digunakan seperti yang ditunjukkan padaKlien HTTP yang dapat dikonfigurasi bagian.

catatan

Untuk sebagian besar klien layanan, seperti Amazon S3, SDK for Java secara otomatis menambahkan implementasiSdkHttpClient atauSdkHttpAsyncClient antarmuka. Jika klien metadata Anda menggunakan implementasi yang sama, makaEc2MetadataClient#create() akan bekerja. Jika Anda memerlukan implementasi yang berbeda, Anda harus menentukannya saat membuat klien metadata.

Kirim permintaan

Untuk mengambil metadata contoh, instantiateEC2MetadataClient kelas dan memanggilget metode dengan parameter path yang menentukan kategori metadata instance.

Contoh berikut mencetak nilai yang terkait denganami-id kunci ke konsol.

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.

Jika jalan tidak valid,get metode ini akan melempar eksepsi.

Gunakan kembali instance klien yang sama untuk beberapa permintaan, tetapi hubungiclose klien ketika tidak lagi diperlukan untuk melepaskan sumber daya. Setelah metode close dipanggil, instance klien tidak dapat digunakan lagi.

Mengurai Tanggapan

EC2 contoh metadata dapat output dalam format yang berbeda. Teks biasa dan JSON adalah format yang paling umum digunakan. Klien metadata menawarkan cara untuk bekerja dengan format tersebut.

Seperti contoh berikut menunjukkan, menggunakanasString metode untuk mendapatkan data sebagai string Java. Anda juga dapat menggunakanasList metode untuk memisahkan respons teks biasa yang mengembalikan beberapa baris.

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

Jika responsnya ada di JSON, gunakanEc2MetadataResponse#asDocument metode ini untuk mengurai respons JSON menjadi instance Document seperti yang ditunjukkan pada cuplikan kode berikut.

Document fullResponse = response.asDocument();

Pengecualian akan dilemparkan jika format metadata tidak dalam JSON. Jika respons berhasil diurai, Anda dapat menggunakan API dokumen untuk memeriksa respons secara lebih rinci. Lihat bagan kategori metadata instans untuk mempelajari kategori metadata mana yang memberikan respons berformat JSON.

Konfigurasi klien metadata

Percobaan ulang

Anda dapat mengkonfigurasi klien metadata dengan mekanisme coba lagi. Jika Anda melakukannya, maka klien dapat secara otomatis mencoba kembali permintaan yang gagal karena alasan yang tidak terduga. Secara default, klien mencoba ulang tiga kali pada permintaan gagal dengan waktu backoff eksponensial antara upaya.

Jika kasus penggunaan Anda memerlukan mekanisme percobaan ulang yang berbeda, Anda dapat menyesuaikan klien menggunakanretryPolicy metode pada pembangunnya. Misalnya, contoh berikut menunjukkan klien sinkron yang dikonfigurasi dengan penundaan tetap dua detik antara upaya dan lima upaya coba lagi.

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

Ada beberapa BackoffStrategiesyang dapat Anda gunakan dengan klien metadata.

Anda juga dapat menonaktifkan mekanisme percobaan ulang sepenuhnya, seperti yang ditunjukkan cuplikan berikut.

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

MenggunakanEc2MetadataRetryPolicy#none() menonaktifkan kebijakan coba ulang default sehingga klien metadata mencoba tidak ada percobaan ulang.

Versi IP

Secara default, klien metadata menggunakan titik akhir IPV4 dihttp://169.254.169.254. Untuk mengubah klien untuk menggunakan versi IPV6, gunakan salah satuendpointMode atauendpoint metode pembangun. Hasil pengecualian jika kedua metode dipanggil pada pembangun.

Contoh berikut ini menunjukkan kedua opsi IPV6.

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

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

Fitur kunci

Klien asinkron

Untuk menggunakan versi non-blocking klien, instantiate instance dariEc2MetadataAsyncClient kelas. Kode dalam contoh berikut membuat klien asynchronous dengan pengaturan default dan menggunakanget metode untuk mengambil nilai untukami-id kunci.

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

Yangjava.util.concurrent.CompletableFuture dikembalikan olehget metode selesai ketika respon kembali. Contoh berikut mencetakami-id metadata ke konsol.

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

Klien HTTP yang dapat dikonfigurasi

Pembangun untuk setiap klien metadata memilikihttpClient metode yang dapat Anda gunakan untuk memasok klien HTTP yang disesuaikan.

Contoh berikut menunjukkan kode untukUrlConnectionHttpClient contoh kustom.

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.

Contoh berikut menunjukkan kode untukNettyNioAsyncHttpClient instance kustom dengan klien metadata asinkron.

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.

Klien HTTPTopik dalam panduan ini memberikan rincian tentang cara mengkonfigurasi klien HTTP yang tersedia di SDK for Java.

Caching Token

Karena klien metadata menggunakan IMDSv2, semua permintaan dikaitkan dengan sesi. Sesi didefinisikan oleh token yang memiliki kedaluwarsa, yang dikelola klien metadata untuk Anda. Setiap permintaan metadata secara otomatis menggunakan kembali token hingga kedaluwarsa.

Secara default-nya, token berlangsung selama enam jam (21.600 detik). Kami sarankan Anda menyimpan time-to-live default-nya, kecuali kasus penggunaan spesifik Anda memerlukan konfigurasi lanjutan.

Jika diperlukan, konfigurasikan durasi dengan menggunakan metodetokenTtl pembangun. Misalnya, kode dalam cuplikan berikut membuat klien dengan durasi sesi lima menit.

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

Jika Anda menghilangkan panggilantokenTtl metode pada builder, durasi default 21.600 digunakan sebagai gantinya.