Änderungen im EC2-Metadaten-Dienstprogramm von Version 1 zu Version 2 - AWS SDK for Java 2.x
Allgemeine ÄnderungenVerhaltensänderungenKonfigurationsunterschiede

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-Dienstprogramm von Version 1 zu Version 2

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

Allgemeine Änderungen

Ä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.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>
Package name com.amazonaws.util software.amazon.awssdk.imds
Instanziierungsansatz

Verwenden Sie statische Dienstprogrammmethoden; 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();
Client-Typen Synchrone Dienstprogrammmethoden: EC2MetadataUtils

Synchron: Ec2MetadataClient

Asynchron: Ec2MetadataAsyncClient

1 Neueste Version . 2 Neueste Version .

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

Anfordern von Metadaten

In v1 verwenden Sie statische Methoden, die keine Parameter akzeptieren, um Metadaten für eine EC2-Ressource anzufordern. Im Gegensatz dazu müssen Sie den Pfad zur EC2-Ressource als Parameter in v2 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 Metadatenkategorien der Instance finden Sie den Pfad, den Sie angeben müssen, um Metadaten anzufordern.

Anmerkung

Wenn Sie einen Instance-Metadaten-Client in v2 verwenden, sollten Sie versuchen, für alle Anfragen zum Abrufen von Metadaten denselben Client 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 Instance-Identitätsdokuments .

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

In der folgenden Tabelle wird verglichen, wie Sie Metadaten eines Instance-Identitätsdokuments in v1 und v2 abrufen.

Anwendungsfall v1 v2
Abrufen der Region 
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();
Abrufen der Instance-ID 
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();
Abrufen des Instance-Typs 
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 Endpunktauflösung

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

v1 v2
Systemeigenschaft: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride Client-Builder-Konfigurationsmethode: endpoint(...)
Umgebungsvariable: AWS_EC2_METADATA_SERVICE_ENDPOINT Systemeigenschaft: aws.ec2MetadataServiceEndpoint
Standardwert: http://169.254.169.254 Config-Datei: ~.aws/config mit der ec2_metadata_service_endpoint Einstellung
Wert im Zusammenhang mit aufgelösten endpoint-mode
Standardwert: http://169.254.169.254

Endpunktauflösung in v2

Wenn Sie explizit einen Endpunkt mithilfe des Builders 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 Konfigurationsdateieinstellung ignoriert, wenn sie vorhanden sind.

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

Endpunktmodus

Mit v2 können Sie einen Endpunktmodus angeben, um den Metadaten-Client so zu konfigurieren, dass er die Standardendpunktwerte für IPv4 oder IPv6 verwendet. Der Endpunktmodus ist für v1 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, wie Sie den Endpunktmodus in der Reihenfolge der absteigenden Priorität festlegen können.

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)
In den vorherigen Methoden nicht angegeben IPv4 wird verwendet

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

  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 endpoint sowohl als auch im Client Builder aufgerufen endpointMode werden, verwendet das SDK den Endpunktwert der 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 prüft zunächst auf einen 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 keine externen Einstellungen findet und Sie den Metadaten-Client nicht im Code konfiguriert haben, verwendet das SDK schließlich den IPv4-Wert von http://169.254.169.254.

IMDSv2

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

  • Instance Metadata Service Version 1 (IMDSv1) – Anfrage-/Antwortansatz

  • Instance Metadata Service Version 2 (IMDSv2) – Sitzungsorientierter Ansatz

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

v1 v2
IMDSv2 wird standardmäßig verwendet Verwendet immer IMDSv2
Versucht, ein Sitzungstoken für jede Anforderung abzurufen, und greift auf IMDSv1 zurück, wenn es ein Sitzungstoken nicht abrufen kann Behält ein Sitzungstoken in einem internen Cache, der für mehrere Anforderungen wiederverwendet wird

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

Konfigurationsunterschiede

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

Konfiguration v1 v2
Wiederholversuche Konfiguration nicht verfügbar Über Builder-Methode konfigurierbar retryPolicy(...)
HTTP Verbindungs-Timeout, das über die AWS_METADATA_SERVICE_TIMEOUT Umgebungsvariable konfiguriert werden kann. Der Standardwert 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();