Perubahan utilitas EC2 metadata 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 EC2 metadata 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).

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.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 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 EC2 metadata memerlukan implementasi SdkHttpClient antarmuka untuk klien metadata sinkron, atau SdkAsyncHttpClient antarmuka untuk klien metadata asinkron. HTTPklienBagian ini menunjukkan daftar HTTP klien 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 EC2 sumber daya 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

JSONdata

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

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

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 SDK diperiksa 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 agar menggunakan nilai titik akhir default untuk atau. IPv4 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] untukIPv6.

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 IPv4digunakan

Bagaimana SDK menyelesaikan endpoint atau di v2 endpoint-mode

  1. SDKMenggunakan 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 tampilan ke konfigurasi eksternal—pertama untuk properti sistem dan kemudian untuk pengaturan dalam file konfigurasi.

    1. Yang SDK pertama memeriksa nilai endpoint. Jika nilai ditemukan, itu digunakan.

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

  3. Akhirnya, jika tidak SDK menemukan pengaturan eksternal dan Anda belum mengkonfigurasi klien metadata dalam kode, SDK menggunakan IPv4 nilai. http://169.254.169.254

IMDSv2

Amazon EC2 mendefinisikan dua pendekatan untuk mengakses metadata instance:

  • Layanan Metadata Instance Versi 1 (IMDSv1) — Pendekatan permintaan/respons

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

Tabel berikut membandingkan bagaimana Java SDKs bekerja denganIMDS.

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

SDKUntuk Java 2.x hanya mendukung IMDSv2 dan tidak kembali keIMDSv1.

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 HTTP klien ke metode pembangunhttpClient(...). Batas waktu koneksi default untuk HTTP klien adalah 2 detik.

Contoh HTTP konfigurasi 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();