View a markdown version of this page

Änderungen im EC2-Metadaten-Utility von Version 1 zu Version 2 - AWS SDK for Java 2.x
High-level ÄnderungenVerhaltensänderungenUnterschiede in der Konfiguration

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

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

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

High-level Änderungen

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

1 Aktuelle Version. 2 Letzte Version.

3 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 Konfigurieren Sie HTTP-Clients in der AWS SDK for Java 2.x 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 Version 2 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();

In den Kategorien für Instanz-Metadaten finden Sie den Pfad, den Sie angeben müssen, um Metadaten anzufordern.

Anmerkung

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

Verhaltensänderungen

JSON-Daten

Auf EC2 gibt der lokal ausgeführte Instance Metadata Service (IMDS) einige Metadaten als JSON-formatierte Zeichenfolgen zurück. Ein solches Beispiel sind die dynamischen Metadaten eines Instanz-Identitä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();
Ruft 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();
Ruft 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 in der Auflösung der Endpunkte

Die folgende Tabelle zeigt die Speicherorte, die das SDK überprüft, um den Endpunkt für IMDS aufzulösen. Die Standorte sind in absteigender Priorität aufgeführt.

v1   v2
Systemeigenschaft: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride Methode zur Konfiguration des Client Builders: 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 resolved verknüpft ist endpoint-mode
Standardwert: http://169.254.169.254

Auflösung des Endpunkts 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, falls sie vorhanden sind.

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

Endpoint-mode

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

Die folgende Tabelle zeigt die verschiedenen Möglichkeiten, den Endpunktmodus in absteigender Reihenfolge der Priorität einzustellen.

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

Wie löst das SDK den Endpunkt - oder Endpunktmodus in Version 2 auf

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

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

    1. Das SDK sucht zuerst 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 Methoden für den Zugriff auf Instance-Metadaten:

  • Instance Metadata Service Version 1 (IMDSv1) — Ansatz Request/response

  • Instanz-Metadatendienst Version 2 (IMDSv2) — Ansatz Session-oriented

In der folgenden Tabelle wird verglichen, wie die Java-SDKs mit IMDS zusammenarbeiten.

v1   v2
IMDSv2 wird standardmäßig verwendet Verwendet immer IMDSv2
Versucht, für jede Anfrage ein Sitzungstoken abzurufen, und greift auf IMDSv1 zurück, wenn kein Sitzungstoken abgerufen werden kann Bewahrt ein Sitzungstoken in einem internen Cache auf, das für mehrere Anfragen wiederverwendet wird

Das SDK für Java 2.x unterstützt nur IMDSv2 und greift nicht auf IMDSv1 zurück.

Unterschiede in der Konfiguration

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

Konfiguration v1   v2
Erneute Versuche Konfiguration nicht verfügbar Konfigurierbar über die Builder-Methode retryPolicy(...)
HTTP Das Verbindungs-Timeout ist über die AWS_METADATA_SERVICE_TIMEOUT Umgebungsvariable konfigurierbar. Die Standardeinstellung ist 1 Sekunde. Die Konfiguration ist verfügbar, indem ein HTTP-Client an die Builder-Methode übergeben wirdhttpClient(...). Das Standard-Verbindungs-Timeout 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 Verbindungs-Timeout konfiguriert und der Apache HTTP-Client verwendet.

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

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