View a markdown version of this page

Perubahan utilitas metadata EC2 dari versi 1 ke versi 2 - AWS SDK for Java 2.x
High-level perubahanPerubahan perilakuPerbedaan konfigurasi

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Perubahan utilitas metadata EC2 dari versi 1 ke versi 2

Topik ini merinci perubahan utilitas metadata SDK untuk Java Amazon Elastic Compute Cloud (EC2) dari versi 1 (v1) ke versi 2 (v2).

High-level perubahan

Ubah v1 v2

Ketergantungan 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.27.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>
Nama paket com.amazonaws.util software.amazon.awssdk.imds
Pendekatan instantiasi

Gunakan metode utilitas statis; tidak ada instantiasi:

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

Gunakan metode pabrik statis:

Ec2MetadataClient client = Ec2MetadataClient.create();

Atau gunakan pendekatan pembangun:

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();
Jenis klien Metode utilitas hanya sinkron: EC2MetadataUtils

Sinkron: Ec2MetadataClient

Asinkron: Ec2MetadataAsyncClient

1 Versi terbaru. 2 Versi terbaru.

3 Perhatikan deklarasi apache-client modul untuk v2. V2 utilitas metadata EC2 memerlukan implementasi SdkHttpClient antarmuka untuk klien metadata sinkron, atau SdkAsyncHttpClient antarmuka untuk klien metadata asinkron. Konfigurasikan klien HTTP di AWS SDK for Java 2.xBagian ini menunjukkan daftar klien HTTP yang dapat Anda gunakan.

Meminta metadata

Di v1, Anda menggunakan metode statis yang tidak menerima parameter untuk meminta metadata untuk sumber daya EC2. Sebaliknya, Anda perlu menentukan jalur ke sumber daya EC2 sebagai parameter di v2. Tabel berikut menunjukkan pendekatan yang berbeda.

v1 v2 
String userMetaData = EC2MetadataUtils.getUserData();
 
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = 
                client.get("/latest/user-data");
String userMetaData = 
                response.asString();

Lihat kategori metadata instance untuk menemukan jalur yang perlu Anda berikan untuk meminta sepotong metadata.

catatan

Saat Anda menggunakan klien metadata instance di v2, Anda harus bertujuan untuk menggunakan klien yang sama untuk semua permintaan untuk mengambil metadata.

Perubahan perilaku

Data JSON

Pada EC2, Instance Metadata Service (IMDS) yang berjalan secara lokal mengembalikan beberapa metadata sebagai string berformat JSON. Salah satu contohnya adalah metadata dinamis dari dokumen identitas instance.

API v1 berisi metode terpisah untuk setiap bagian metadata identitas instance, sedangkan API v2 secara langsung mengembalikan string JSON. Untuk bekerja dengan string JSON, Anda dapat menggunakan API Dok umen untuk mengurai respons dan menavigasi struktur JSON.

Tabel berikut membandingkan cara Anda mengambil metadata dokumen identitas instance di v1 dan v2.

Kasus penggunaan v1 v2
Mengambil Wilayah 
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();
Ambil id instance 
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();
Mengambil jenis instance 
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();

Perbedaan resolusi titik akhir

Tabel berikut menunjukkan lokasi yang diperiksa SDK untuk menyelesaikan titik akhir ke IMDS. Lokasi terdaftar dalam prioritas menurun.

v1 v2
Properti sistem: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride Metode konfigurasi pembangun klien: endpoint(...)
Variabel lingkungan: AWS_EC2_METADATA_SERVICE_ENDPOINT Properti sistem: aws.ec2MetadataServiceEndpoint
Nilai Default: http://169.254.169.254 File konfigurasi: ~.aws/config dengan ec2_metadata_service_endpoint pengaturan
Nilai yang terkait dengan diselesaikan endpoint-mode
Nilai default: http://169.254.169.254

Resolusi titik akhir dalam v2

Ketika Anda secara eksplisit menetapkan titik akhir dengan menggunakan pembangun, nilai titik akhir itu diprioritaskan di atas semua pengaturan lainnya. Ketika kode berikut dieksekusi, properti aws.ec2MetadataServiceEndpoint sistem dan ec2_metadata_service_endpoint pengaturan file konfigurasi diabaikan jika ada.

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

Endpoint-mode

Dengan v2, Anda dapat menentukan mode titik akhir untuk mengonfigurasi klien metadata untuk menggunakan nilai titik akhir default untuk IPv4 atau IPv6. Endpoint-mode tidak tersedia untuk v1. Nilai default yang digunakan untuk IPv4 adalah http://169.254.169.254 dan http://[fd00:ec2::254] untuk IPv6.

Tabel berikut menunjukkan berbagai cara Anda dapat mengatur mode titik akhir dalam urutan prioritas menurun.

Kemungkinan nilai
Metode konfigurasi pembangun klien: endpointMode(...) 
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();
 EndpointMode.IPV4, EndpointMode.IPV6
Properti sistem aws.ec2MetadataServiceEndpointMode IPv4, IPv6 (kasus tidak masalah)
Berkas konfigurasi: ~.aws/config Setelan ec2_metadata_service_endpoint IPv4, IPv6 (kasus tidak masalah)
Tidak ditentukan dengan cara sebelumnya IPv4 digunakan

Bagaimana SDK menyelesaikan titik akhir atau mode titik akhir di v2

  1. SDK menggunakan nilai yang Anda tetapkan dalam kode pada pembuat klien dan mengabaikan pengaturan eksternal apa pun. Karena SDK melempar pengecualian jika keduanya endpoint dan endpointMode dipanggil pada pembuat klien, SDK menggunakan nilai titik akhir dari metode mana pun yang Anda gunakan.

  2. Jika Anda tidak menetapkan nilai dalam kode, SDK melihat ke konfigurasi eksternal—pertama untuk properti sistem dan kemudian untuk pengaturan dalam file konfigurasi.

    1. SDK pertama-tama memeriksa nilai titik akhir. Jika suatu nilai ditemukan, itu digunakan.

    2. Jika SDK masih belum menemukan nilai, SDK mencari pengaturan mode titik akhir.

  3. Terakhir, jika SDK tidak menemukan pengaturan eksternal dan Anda belum mengonfigurasi klien metadata dalam kode, SDK menggunakan nilai IPv4 darihttp://169.254.169.254.

IMDSv2

Amazon EC2 mendefinisikan dua pendekatan untuk mengakses metadata instans:

  • Layanan Metadata Instance Versi 1 (IMDSv1) - pendekatan Request/response

  • Layanan Metadata Instance Versi 2 (IMDSv2) - pendekatan Session-oriented

Tabel berikut membandingkan bagaimana Java SDK bekerja dengan IMDS.

v1 v2
IMDSv2 digunakan secara default Selalu menggunakan IMDSv2
Mencoba mengambil token sesi untuk setiap permintaan dan kembali ke IMDSv1 jika gagal mengambil token sesi Menyimpan token sesi dalam cache internal yang digunakan kembali untuk beberapa permintaan

SDK untuk Java 2.x hanya mendukung IMDSv2 dan tidak kembali ke IMDSv1.

Perbedaan konfigurasi

Tabel berikut mencantumkan opsi konfigurasi yang berbeda.

Konfigurasi v1 v2
Percobaan ulang Konfigurasi tidak tersedia Dapat dikonfigurasi melalui metode pembangun retryPolicy(...)
HTTP Waktu tunggu koneksi dapat dikonfigurasi melalui variabel AWS_METADATA_SERVICE_TIMEOUT lingkungan. Defaultnya adalah 1 detik. Konfigurasi tersedia dengan meneruskan klien HTTP ke metode pembangunhttpClient(...). Batas waktu koneksi default untuk klien HTTP adalah 2 detik.

Contoh konfigurasi HTTP v2

Contoh berikut menunjukkan bagaimana Anda dapat mengkonfigurasi klien metadata. Contoh ini mengonfigurasi batas waktu koneksi dan menggunakan klien HTTP Apache.

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

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