Perubahan utilitas metadata EC2 dari versi 1 ke versi 2 - AWS SDK for Java 2.x
Perubahan tingkat tinggiPerubahan 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 for Java Amazon Elastic Compute Cloud (EC2) dari versi 1 (v1) ke versi 2 (v2).

Perubahan tingkat tinggi

Perubahan 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.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>
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 Hanya metode utilitas sinkron: EC2MetadataUtils

Sinkron: Ec2MetadataClient

Asinkron: Ec2MetadataAsyncClient

1 Versi terbaru. 2 Versi terbaru.

3 Perhatikan deklarasi apache-client modul untuk v2. V2 dari utilitas metadata EC2 memerlukan implementasi SdkHttpClient antarmuka untuk klien metadata sinkron, atau antarmuka untuk klien metadata SdkAsyncHttpClient asinkron. HTTPklienBagian 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

Ketika 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, Layanan Metadata Instance (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 Document API untuk mengurai respons dan menavigasi struktur JSON.

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

Kasus penggunaan v1 v2
Ambil 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();
Ambil 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 IMDS. Lokasi tercantum 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 pengaturan ec2_metadata_service_endpoint
Nilai yang terkait dengan diselesaikan endpoint-mode
Nilai default: http://169.254.169.254

Resolusi titik akhir di v2

Saat Anda secara eksplisit menetapkan titik akhir dengan menggunakan pembuat, nilai titik akhir tersebut diprioritaskan di atas semua pengaturan lainnya. Ketika kode berikut dijalankan, 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();

Modus titik akhir

Dengan v2, Anda dapat menentukan mode titik akhir untuk mengonfigurasi klien metadata untuk menggunakan nilai titik akhir default untuk IPv4 atau IPv6. Mode titik akhir 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 yang dapat Anda atur mode endpoint 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 Config: ~.aws/config Setelan ec2_metadata_service_endpoint IPv4, IPv6 (kasus tidak masalah)
Tidak ditentukan dengan cara sebelumnya IPv4 digunakan

Bagaimana SDK menyelesaikan endpoint atau di v2 endpoint-mode

  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 nilai ditemukan, itu digunakan.

    2. Jika SDK masih belum menemukan nilai, SDK akan 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 dari. http://169.254.169.254

IMDSv2

Amazon EC2 mendefinisikan dua pendekatan untuk mengakses metadata instans:

  • Layanan Metadata Instans Versi 1 (IMDSv1) - pendekatan permintaan/respons

  • Layanan Metadata Instance Versi 2 (IMDSv2) — Pendekatan berorientasi sesi

Tabel berikut membandingkan bagaimana SDK Java 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 for 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 Batas waktu koneksi dapat dikonfigurasi melalui variabel AWS_METADATA_SERVICE_TIMEOUT lingkungan. Defaultnya adalah 1 detik. Konfigurasi tersedia dengan meneruskan klien HTTP ke metode builderhttpClient(...). 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 mengkonfigurasi batas waktu koneksi dan menggunakan klien HTTP Apache.

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

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