Änderungen im EC2 Metadaten-Hilfsprogramm von Version 1 zu Version 2

In diesem Thema werden die Änderungen im Metadaten-Hilfsprogramm SDK for Java Amazon Elastic Compute Cloud (EC2) von Version 1 (v1) auf Version 2 (v2) beschrieben.

Änderungen auf hoher Ebene

Änderung	v1	v2
Maven-Abhängigkeiten	<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>
Package name	com.amazonaws.util	software.amazon.awssdk.imds
Instanziierungsansatz	Verwenden Sie statische Hilfsmethoden; keine Instanziierung: String localHostName = EC2MetadataUtils.getLocalHostName();	Verwenden Sie eine statische Factory-Methode: Ec2MetadataClient client = Ec2MetadataClient.create(); Oder verwenden Sie einen Builder-Ansatz: Ec2MetadataClient client = Ec2MetadataClient.builder() .endpointMode(EndpointMode.IPV6) .build();
Arten von Kunden	Nur synchrone Hilfsmethoden: EC2MetadataUtils	Synchron: Ec2MetadataClient Asynchron: Ec2MetadataAsyncClient

¹ Letzte Version. ² Letzte Version.

³ Beachten Sie die Deklaration des apache-client Moduls für v2. V2 des EC2 Metadaten-Dienstprogramms erfordert eine Implementierung der SdkHttpClient Schnittstelle für den synchronen Metadaten-Client oder der SdkAsyncHttpClient Schnittstelle für den asynchronen Metadaten-Client. Der HTTP-Clients Abschnitt zeigt die Liste der HTTP-Clients, die Sie verwenden können.

Metadaten anfordern

In Version 1 verwenden Sie statische Methoden, die keine Parameter akzeptieren, um Metadaten für eine EC2 Ressource anzufordern. Im Gegensatz dazu müssen Sie in v2 den Pfad zur EC2 Ressource als Parameter angeben. Die folgende Tabelle zeigt die verschiedenen Ansätze.

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

Den Pfad, den Sie angeben müssen, um Metadaten anzufordern, finden Sie in den Kategorien der Instanz-Metadaten.

Anmerkung

Wenn Sie in Version 2 einen Instanz-Metadaten-Client verwenden, sollten Sie versuchen, für alle Anfragen zum Abrufen von Metadaten denselben Client zu verwenden.

Das Verhalten ändert sich

JSON-Daten

Bei aktivierter EC2 Option gibt der lokal ausgeführte Instanz-Metadatendienst (IMDS) einige Metadaten als Zeichenketten im JSON-Format zurück. Ein solches Beispiel sind die dynamischen Metadaten eines Instanzidentitätsdokuments.

Die v1-API enthält separate Methoden für jeden Teil der Instanzidentitätsmetadaten, wohingegen die v2-API die JSON-Zeichenfolge direkt zurückgibt. Um mit der JSON-Zeichenfolge zu arbeiten, können Sie die Dokument-API verwenden, um die Antwort zu analysieren und in der JSON-Struktur zu navigieren.

In der folgenden Tabelle wird verglichen, wie Sie Metadaten eines Instanzidentitätsdokuments in Version 1 und Version 2 abrufen.

Anwendungsfall	v1	v2
Rufen Sie die Region ab	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();
Rufen Sie die Instanz-ID ab	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();
Rufen Sie den Instanztyp ab	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();

Unterschiede bei der Auflösung von Endpunkten

Die folgende Tabelle zeigt die Speicherorte, nach denen das SDK sucht, um den Endpunkt nach IMDS aufzulösen. Die Standorte sind mit absteigender Priorität aufgeführt.

v1	v2
Systemeigenschaft: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride	Konfigurationsmethode für den Client Builder: endpoint(...)
Umgebungsvariable: AWS_EC2_METADATA_SERVICE_ENDPOINT	Systemeigenschaft: aws.ec2MetadataServiceEndpoint
Standardwert: http://169.254.169.254	Konfigurationsdatei: ~.aws/config mit der ec2_metadata_service_endpoint Einstellung
	Wert, der mit „gelöst“ verknüpft ist endpoint-mode
	Standardwert: http://169.254.169.254

Endpunktauflösung in Version 2

Wenn Sie mithilfe des Builders explizit einen Endpunkt festlegen, hat dieser Endpunktwert Vorrang vor allen anderen Einstellungen. Wenn der folgende Code ausgeführt wird, werden die aws.ec2MetadataServiceEndpoint Systemeigenschaft und die ec2_metadata_service_endpoint Einstellung der Konfigurationsdatei ignoriert, sofern sie existieren.

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

Endpoint-Modus

Mit v2 können Sie einen Endpunktmodus angeben, um den Metadaten-Client so zu konfigurieren, dass er die Standard-Endpunktwerte für oder verwendet. IPv4 IPv6 Der Endpunktmodus ist für Version 1 nicht verfügbar. Der für verwendete Standardwert IPv4 ist http://169.254.169.254 und http://[fd00:ec2::254] für. IPv6

Die folgende Tabelle zeigt die verschiedenen Möglichkeiten, wie Sie den Endpunktmodus nach absteigender Priorität einstellen können.

		Mögliche Werte
Konfigurationsmethode für den Client Builder: endpointMode(...)	Ec2MetadataClient client = Ec2MetadataClient .builder() .endpointMode(EndpointMode.IPV4) .build();	EndpointMode.IPV4, EndpointMode.IPV6
Systemeigenschaft	aws.ec2MetadataServiceEndpointMode	IPv4, IPv6 (Groß- und Kleinschreibung spielt keine Rolle)
Konfigurationsdatei: ~.aws/config	ec2_metadata_service_endpoint-Einstellung	IPv4, IPv6 (Groß- und Kleinschreibung spielt keine Rolle)
Auf die vorherigen Arten nicht angegeben	IPv4 wird verwendet

Wie das SDK auflöst endpoint oder endpoint-mode in v2

1. Das SDK verwendet den Wert, den Sie im Code auf dem Client Builder festgelegt haben, und ignoriert alle externen Einstellungen. Da das SDK bei beiden eine Ausnahme auslöst endpoint und endpointMode im Client Builder aufgerufen wird, verwendet das SDK den Endpunktwert der von Ihnen verwendeten Methode.

2. Wenn Sie keinen Wert im Code festlegen, sucht das SDK nach einer externen Konfiguration — zuerst nach Systemeigenschaften und dann nach einer Einstellung in der Konfigurationsdatei.

   1. Das SDK sucht zunächst nach einem Endpunktwert. Wenn ein Wert gefunden wird, wird er verwendet.

   2. Wenn das SDK immer noch keinen Wert gefunden hat, sucht das SDK nach Einstellungen für den Endpunktmodus.

3. Wenn das SDK schließlich keine externen Einstellungen findet und Sie den Metadaten-Client nicht im Code konfiguriert haben, verwendet das SDK den IPv4 Wert vonhttp://169.254.169.254.

IMDSv2

Amazon EC2 definiert zwei Ansätze für den Zugriff auf Instance-Metadaten:

• Instance-Metadaten-Service Version 1 (IMDSv1) — Anforderungs-/Antwort-Ansatz

• Instanz-Metadatendienst Version 2 (IMDSv2) — Sitzungsorientierter Ansatz

In der folgenden Tabelle wird verglichen, wie Java mit SDKs IMDS funktioniert.

v1	v2
IMDSv2 wird standardmäßig verwendet	Benutzt immer IMDSv2
Versucht, für jede Anfrage ein Sitzungstoken abzurufen, und greift darauf zurück, IMDSv1 wenn ein Sitzungstoken nicht abgerufen werden kann	Speichert ein Sitzungstoken in einem internen Cache, der für mehrere Anfragen wiederverwendet wird

Das SDK for Java 2.x unterstützt nur IMDSv2 und greift nicht darauf IMDSv1 zurück.

Unterschiede in der Konfiguration

In der folgenden Tabelle sind die unterschiedlichen Konfigurationsoptionen aufgeführt.

Konfiguration	v1	v2
Wiederholversuche	Konfiguration nicht verfügbar	Konfigurierbar über die Builder-Methode retryPolicy(...)
HTTP	Verbindungs-Timeout, konfigurierbar über die AWS_METADATA_SERVICE_TIMEOUT Umgebungsvariable. Die Standardeinstellung ist 1 Sekunde.	Die Konfiguration ist verfügbar, indem ein HTTP-Client an die Builder-Methode übergeben wirdhttpClient(...). Das standardmäßige Verbindungstimeout für HTTP-Clients beträgt 2 Sekunden.

Beispiel für eine v2-HTTP-Konfiguration

Das folgende Beispiel zeigt, wie Sie den Metadaten-Client konfigurieren können. In diesem Beispiel wird das Verbindungstimeout konfiguriert und der Apache HTTP-Client verwendet.

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

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