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.
Dieses Thema enthält step-by-step Anweisungen zur Migration Ihres Verbrauchers von KCL 2.x zu KCL 3.x. KCL 3.x unterstützt die direkte Migration von KCL 2.x-Verbrauchern. Sie können weiterhin die Daten aus Ihrem Kinesis-Datenstrom nutzen und gleichzeitig Ihre Mitarbeiter fortlaufend migrieren.
Wichtig
KCL 3.x verwendet dieselben Schnittstellen und Methoden wie KCL 2.x. Daher müssen Sie Ihren Datensatzverarbeitungscode während der Migration nicht aktualisieren. Sie müssen jedoch die richtige Konfiguration festlegen und die erforderlichen Schritte für die Migration überprüfen. Wir empfehlen Ihnen dringend, die folgenden Migrationsschritte zu befolgen, um eine reibungslose Migration zu gewährleisten.
Schritt 1: Voraussetzungen
Bevor Sie mit der Verwendung von KCL 3.x beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:
-
Java Development Kit (JDK) 8 oder höher
-
AWS SDK for Java 2.x
-
Maven oder Gradle für das Abhängigkeitsmanagement
Wichtig
Verwenden Sie nicht die AWS SDK for Java Versionen 2.27.19 bis 2.27.23 mit KCL 3.x. Diese Versionen enthalten ein Problem, das einen Ausnahmefehler im Zusammenhang mit der DynamoDB-Nutzung von KCL verursacht. Wir empfehlen, die AWS SDK for Java Version 2.28.0 oder höher zu verwenden, um dieses Problem zu vermeiden.
Schritt 2: Abhängigkeiten hinzufügen
Wenn Sie Maven verwenden, fügen Sie Ihrer pom.xml Datei die folgende Abhängigkeit hinzu. Stellen Sie sicher, dass Sie 3.x.x durch die neueste KCL-Version ersetzt haben.
<dependency>
<groupId>software.amazon.kinesis</groupId>
<artifactId>amazon-kinesis-client</artifactId>
<version>3.x.x</version> <!-- Use the latest version -->
</dependency>Wenn Sie Gradle verwenden, fügen Sie Ihrer Datei Folgendes hinzu. build.gradle Stellen Sie sicher, dass Sie 3.x.x durch die neueste KCL-Version ersetzt haben.
implementation 'software.amazon.kinesis:amazon-kinesis-client:3.x.x'Sie können im Maven Central Repository nach der neuesten Version der KCL suchen.
Schritt 3: Richten Sie die migrationsbezogene Konfiguration ein
Um von KCL 2.x zu KCL 3.x zu migrieren, müssen Sie den folgenden Konfigurationsparameter festlegen:
-
CoordinatorConfig. clientVersionConfig: Diese Konfiguration bestimmt, in welchem KCL-Versionskompatibilitätsmodus die Anwendung ausgeführt wird. Bei der Migration von KCL 2.x auf 3.x müssen Sie diese Konfiguration auf einstellen.
CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2XUm diese Konfiguration festzulegen, fügen Sie bei der Erstellung Ihres Scheduler-Objekts die folgende Zeile hinzu:
configsBuilder.coordiantorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPLATIBLE_WITH_2X)Im Folgenden finden Sie ein Beispiel dafür, wie Sie den CoordinatorConfig.clientVersionConfig für die Migration von KCL 2.x auf 3.x festlegen. Sie können andere Konfigurationen nach Bedarf an Ihre spezifischen Anforderungen anpassen:
Scheduler scheduler = new Scheduler(
configsBuilder.checkpointConfig(),
configsBuilder.coordiantorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPLATIBLE_WITH_2X),
configsBuilder.leaseManagementConfig(),
configsBuilder.lifecycleConfig(),
configsBuilder.metricsConfig(),
configsBuilder.processorConfig(),
configsBuilder.retrievalConfig()
);Es ist wichtig, dass alle Worker in Ihrer Consumer-Anwendung zu einem bestimmten Zeitpunkt denselben Load-Balancing-Algorithmus verwenden, da KCL 2.x und 3.x unterschiedliche Load-Balancing-Algorithmen verwenden. Das Ausführen von Workern mit unterschiedlichen Load-Balancing-Algorithmen kann zu einer suboptimalen Lastverteilung führen, da die beiden Algorithmen unabhängig voneinander arbeiten.
Diese KCL 2.x-Kompatibilitätseinstellung ermöglicht es Ihrer KCL 3.x-Anwendung, in einem mit KCL 2.x kompatiblen Modus zu laufen und den Load-Balancing-Algorithmus für KCL 2.x zu verwenden, bis alle Worker in Ihrer Consumer-Anwendung auf KCL 3.x aktualisiert wurden. Wenn die Migration abgeschlossen ist, wechselt KCL automatisch in den vollen KCL 3.x-Funktionsmodus und beginnt mit der Verwendung eines neuen KCL 3.x-Lastenausgleichsalgorhythmus für alle laufenden Worker.
Wichtig
Wenn Sie Konfigurationen nicht verwenden, ConfigsBuilder sondern ein LeaseManagementConfig Objekt erstellen, müssen Sie einen weiteren Parameter hinzufügen, der applicationName in KCL-Version 3.x oder höher aufgerufen wird. Einzelheiten finden Sie unter Kompilierungsfehler mit dem LeaseManagementConfig Konstruktor. Wir empfehlen die VerwendungConfigsBuilder, um KCL-Konfigurationen festzulegen. ConfigsBuilderbietet eine flexiblere und wartungsfreundlichere Methode zur Konfiguration Ihrer KCL-Anwendung.
Schritt 4: Folgen Sie den bewährten Methoden für die Implementierung der Methode shutdownRequested ()
Mit KCL 3.x wird eine Funktion namens Graceful Lease Handoff eingeführt, um die erneute Verarbeitung von Daten zu minimieren, wenn ein Leasing im Rahmen der Neuzuweisung eines Leasingvertrags an einen anderen Mitarbeiter übergeben wird. Dies wird erreicht, indem die zuletzt verarbeitete Sequenznummer in der Leasetabelle vor der Leasing-Übergabe überprüft wird. Um sicherzustellen, dass die ordnungsgemäße Lease-Übergabe ordnungsgemäß funktioniert, müssen Sie sicherstellen, dass Sie das checkpointer Objekt innerhalb der shutdownRequested Methode in Ihrer Klasse aufrufen. RecordProcessor Wenn Sie das checkpointer Objekt nicht innerhalb der shutdownRequested Methode aufrufen, können Sie es wie im folgenden Beispiel dargestellt implementieren.
Wichtig
-
Das folgende Implementierungsbeispiel ist eine Mindestanforderung für die reibungslose Leasing-Übergabe. Sie können es bei Bedarf um zusätzliche Logik im Zusammenhang mit dem Checkpointing erweitern. Wenn Sie eine asynchrone Verarbeitung durchführen, stellen Sie sicher, dass alle an den Downstream übermittelten Datensätze verarbeitet wurden, bevor Sie Checkpointing aufrufen.
-
Eine reibungslose Leasing-Übergabe verringert zwar die Wahrscheinlichkeit einer erneuten Verarbeitung von Daten bei Leasing-Übertragungen erheblich, schließt diese Möglichkeit jedoch nicht vollständig aus. Um Datenintegrität und Konsistenz zu wahren, sollten Sie Ihre nachgelagerten Verbraucheranwendungen so gestalten, dass sie idempotent sind. Das bedeutet, dass sie in der Lage sein sollten, die Verarbeitung potenzieller doppelter Datensätze ohne nachteilige Auswirkungen auf das Gesamtsystem zu bewältigen.
/**
* Invoked when either Scheduler has been requested to gracefully shutdown
* or lease ownership is being transferred gracefully so the current owner
* gets one last chance to checkpoint.
*
* Checkpoints and logs the data a final time.
*
* @param shutdownRequestedInput Provides access to a checkpointer, allowing a record processor to checkpoint
* before the shutdown is completed.
*/
public void shutdownRequested(ShutdownRequestedInput shutdownRequestedInput) {
try {
// Ensure that all delivered records are processed
// and has been successfully flushed to the downstream before calling
// checkpoint
// If you are performing any asynchronous processing or flushing to
// downstream, you must wait for its completion before invoking
// the below checkpoint method.
log.info("Scheduler is shutting down, checkpointing.");
shutdownRequestedInput.checkpointer().checkpoint();
} catch (ShutdownException | InvalidStateException e) {
log.error("Exception while checkpointing at requested shutdown. Giving up.", e);
}
}Schritt 5: Überprüfen Sie die KCL 3.x-Voraussetzungen für die Erfassung von Arbeitskräftekennzahlen
KCL 3.x sammelt Metriken zur CPU-Auslastung, wie z. B. die CPU-Auslastung von Mitarbeitern, um die Auslastung gleichmäßig auf die Mitarbeiter verteilen zu können. Anwendungsmitarbeiter für Privatanwender können auf Amazon EC2, Amazon ECS, Amazon EKS oder ausgeführt AWS Fargate werden. KCL 3.x kann Metriken zur CPU-Auslastung von Workern nur erfassen, wenn die folgenden Voraussetzungen erfüllt sind:
Amazon Elastic Compute Cloud(Amazon EC2)
-
Ihr Betriebssystem muss Linux OS sein.
-
Sie müssen es IMDSv2in Ihrer EC2 Instanz aktivieren.
Amazon Elastic Container Service (Amazon ECS) auf Amazon EC2
-
Ihr Betriebssystem muss Linux OS sein.
-
Sie müssen den ECS-Endpunkt für Task-Metadaten, Version 4, aktivieren.
-
Ihre Amazon ECS-Container-Agent-Version muss 1.39.0 oder höher sein.
Amazon ECS auf AWS Fargate
-
Sie müssen den Fargate-Task-Metadaten-Endpunkt Version 4 aktivieren. Wenn Sie die Fargate-Plattformversion 1.4.0 oder höher verwenden, ist dies standardmäßig aktiviert.
-
Fargate-Plattformversion 1.4.0 oder höher.
Amazon Elastic Kubernetes Service (Amazon EKS) auf Amazon EC2
-
Ihr Betriebssystem muss Linux OS sein.
Amazon EKS auf AWS Fargate
-
Fargate-Plattform 1.3.0 oder höher.
Wichtig
Wenn KCL 3.x keine CPU-Nutzungsdaten von Workern sammeln kann, weil die Voraussetzungen nicht erfüllt sind, wird die Last auf das Durchsatzniveau pro Lease verteilt. Dieser Ausweichmechanismus stellt sicher, dass alle Mitarbeiter einen ähnlichen Gesamtdurchsatz aus den Leasingverträgen erhalten, die jedem Mitarbeiter zugewiesen wurden. Weitere Informationen finden Sie unter Wie KCL Mitarbeitern Leasingverträge zuweist und die Arbeitslast verteilt.
Schritt 6: Aktualisieren Sie die IAM-Berechtigungen für KCL 3.x
Sie müssen der IAM-Rolle oder -Richtlinie, die mit Ihrer KCL 3.x-Verbraucheranwendung verknüpft ist, die folgenden Berechtigungen hinzufügen. Dies beinhaltet die Aktualisierung der vorhandenen IAM-Richtlinie, die von der KCL-Anwendung verwendet wird. Weitere Informationen finden Sie unter Für KCL-Anwendungen für Privatanwender sind IAM-Berechtigungen erforderlich.
Wichtig
In Ihren vorhandenen KCL-Anwendungen wurden die folgenden IAM-Aktionen und Ressourcen möglicherweise nicht zur IAM-Richtlinie hinzugefügt, da sie in KCL 2.x nicht benötigt wurden. Stellen Sie sicher, dass Sie sie hinzugefügt haben, bevor Sie Ihre KCL 3.x-Anwendung ausführen:
-
Aktionen:
UpdateTable-
Ressourcen (ARNs):
arn:aws:dynamodb:region:account:table/KCLApplicationName
-
-
Aktionen:
Query-
Ressourcen (ARNs):
arn:aws:dynamodb:region:account:table/KCLApplicationName/Index/*
-
-
Aktionen:
CreateTable,DescribeTableScan,GetItem,PutItem,UpdateItem,DeleteItem-
Ressourcen (ARNs):
arn:aws:dynamodb:region:account:table/KCLApplicationName-WorkerMetricStats,arn:aws:dynamodb:region:account:table/KCLApplicationName-CoordinatorState
Ersetzen Sie „Region“, „Konto“ und „KCLApplicationName“ in der ARNs durch Ihre eigene AWS-Region AWS-Konto Nummer bzw. den Namen der KCL-Anwendung. Wenn Sie Konfigurationen verwenden, um die Namen der von KCL erstellten Metadatentabellen anzupassen, verwenden Sie diese angegebenen Tabellennamen anstelle des KCL-Anwendungsnamens.
-
Schritt 7: Stellen Sie Ihren Mitarbeitern KCL 3.x-Code bereit
Nachdem Sie die für die Migration erforderliche Konfiguration festgelegt und alle vorherigen Migrationschecklisten abgeschlossen haben, können Sie Ihren Code erstellen und für Ihre Mitarbeiter bereitstellen.
Anmerkung
Wenn Sie einen Kompilierungsfehler mit dem LeaseManagementConfig Konstruktor sehen, finden Sie Informationen zur Problembehandlung unter Kompilierungsfehler mit dem LeaseManagementConfig Konstruktor.
Schritt 8: Schließen Sie die Migration ab
Während der Bereitstellung von KCL 3.x-Code verwendet KCL weiterhin den Lease-Zuweisungsalgorithmus aus KCL 2.x. Wenn Sie erfolgreich KCL 3.x-Code für alle Ihre Mitarbeiter bereitgestellt haben, erkennt KCL dies automatisch und wechselt auf den neuen Algorithmus für die Leasingzuweisung, der auf der Ressourcennutzung der Mitarbeiter basiert. Weitere Informationen zum neuen Algorithmus für die Leasingzuweisung finden Sie unter. Wie KCL Mitarbeitern Leasingverträge zuweist und die Arbeitslast verteilt
Während der Bereitstellung können Sie den Migrationsprozess anhand der folgenden Metriken überwachen, die an gesendet CloudWatch werden. Sie können die Metriken während des Migration Vorgangs überwachen. Bei allen Metriken handelt es sich um per-KCL-application Metriken, die auf SUMMARY Metrik-Ebene festgelegt sind. Wenn die Sum Statistik der CurrentState:3xWorker Metrik mit der Gesamtzahl der Mitarbeiter in Ihrer KCL-Anwendung übereinstimmt, bedeutet dies, dass die Migration zu KCL 3.x erfolgreich abgeschlossen wurde.
Wichtig
Es dauert mindestens 10 Minuten, bis KCL auf den neuen Algorithmus für die Zuweisung von Mietverträgen umgestellt hat, nachdem alle Mitarbeiter bereit sind, ihn auszuführen.
| Metriken | Beschreibung |
|---|---|
CurrentState:3xWorker |
Die Anzahl der KCL-Worker, die erfolgreich auf KCL 3.x migriert wurden und den neuen Leasing-Zuweisungsalgorithmus ausführen. Wenn die
|
CurrentState:2xCompatibleWorker |
Die Anzahl der KCL-Worker, die während des Migrationsprozesses im KCL 2.x-kompatiblen Modus ausgeführt werden. Ein Wert ungleich Null für diese Metrik bedeutet, dass die Migration noch im Gange ist.
|
Fault |
Die Anzahl der Ausnahmen, die während des Migrationsprozesses aufgetreten sind. Bei den meisten dieser Ausnahmen handelt es sich um vorübergehende Fehler, und KCL 3.x versucht automatisch erneut, die Migration abzuschließen. Wenn Sie einen dauerhaften
|
GsiStatusReady |
Der Status der Erstellung des globalen Sekundärindex (GSI) in der Leasingtabelle. Diese Metrik gibt an, ob der GSI in der Leasetabelle erstellt wurde. Dies ist eine Voraussetzung für die Ausführung von KCL 3.x. Der Wert ist 0 oder 1, wobei 1 für eine erfolgreiche Erstellung steht. Während eines Rollback-Status wird diese Metrik nicht ausgegeben. Nachdem Sie erneut einen Rollforward durchgeführt haben, können Sie die Überwachung dieser Metrik fortsetzen.
|
workerMetricsReady |
Der Status der Arbeitnehmer misst die Emissionen aller Arbeitnehmer. Die Metriken geben an, ob alle Mitarbeiter Kennzahlen wie die CPU-Auslastung ausgeben. Der Wert ist 0 oder 1, wobei 1 bedeutet, dass alle Mitarbeiter erfolgreich Kennzahlen ausgeben und für den neuen Algorithmus zur Leasingzuweisung bereit sind. Während eines Rollback-Status wird diese Metrik nicht ausgegeben. Nachdem Sie erneut einen Rollforward durchgeführt haben, können Sie die Überwachung dieser Metrik fortsetzen.
|
KCL bietet während der Migration die Möglichkeit, auf den 2.x-kompatiblen Modus zurückzugreifen. Nach erfolgreicher Migration auf KCL 3.x empfehlen wir Ihnen, die CoordinatorConfig.clientVersionConfig Einstellung „CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2XWenn ein Rollback nicht mehr erforderlich ist“ zu entfernen. Durch das Entfernen dieser Konfiguration wird die Ausgabe migrationsbezogener Metriken aus der KCL-Anwendung gestoppt.
Anmerkung
Wir empfehlen Ihnen, die Leistung und Stabilität Ihrer Anwendung für einen bestimmten Zeitraum während der Migration und nach Abschluss der Migration zu überwachen. Wenn Sie Probleme feststellen, können Sie Workers mithilfe des KCL-Migrationstools auf die Verwendung von KCL 2.x-kompatiblen Funktionen zurücksetzen.
