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. # Migrieren Sie von KCL 2.x zu KCL 3.x 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 für Java 2.x + Maven oder Gradle für das Abhängigkeitsmanagement **Wichtig** Verwenden Sie nicht die AWS SDK für 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 für 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. ``` software.amazon.kinesis amazon-kinesis-client 3.x.x ``` 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.](https://search.maven.org/artifact/software.amazon.kinesis/amazon-kinesis-client) ## 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_2X` Um 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](https://docs.aws.amazon.com/streams/latest/dev/troubleshooting-consumers.html#compiliation-error-leasemanagementconfig). Wir empfehlen die Verwendung`ConfigsBuilder`, um KCL-Konfigurationen festzulegen. `ConfigsBuilder`bietet 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 Mietvertrag 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. Anwendungsarbeiter für Privatanwender können auf Amazon EC2, Amazon ECS, Amazon EKS oder AWS Fargate ausgeführt 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 [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)in Ihrer EC2-Instance 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ec2-metadata.html), 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4-fargate.html) 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-Auslastungsmetriken von Workern sammeln kann, weil die Voraussetzungen nicht erfüllt sind, verteilt es die Last auf das Durchsatzniveau pro Lease. 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 Auslastung verteilt](kcl-dynamoDB.md#kcl-assign-leases). ## 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](kcl-iam-permissions.md). **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`, `DescribeTable``Scan`,`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](https://docs.aws.amazon.com/streams/latest/dev/troubleshooting-consumers.html#compilation-error-leasemanagementconfig). ## 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 Auslastung verteilt](kcl-dynamoDB.md#kcl-assign-leases) 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. **CloudWatch Metriken für den KCL-Migrationsprozess** | Kennzahlen | Description | | --- | --- | | CurrentState:3xWorker | Die Anzahl der KCL-Worker, die erfolgreich auf KCL 3.x migriert wurden und den neuen Leasing-Zuweisungsalgorithmus ausführen. Wenn die `Sum` Anzahl dieser Metrik mit der Gesamtzahl Ihrer Mitarbeiter übereinstimmt, bedeutet dies, dass die Migration zu KCL 3.x erfolgreich abgeschlossen wurde. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/streams/latest/dev/kcl-migration-from-2-3.html) | | 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/streams/latest/dev/kcl-migration-from-2-3.html) | | 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 `Fault` Metrikwert beobachten, überprüfen Sie Ihre Protokolle aus dem Migrationszeitraum zur weiteren Fehlerbehebung. Wenn das Problem weiterhin besteht, wenden Sie sich an Support. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/streams/latest/dev/kcl-migration-from-2-3.html) | | 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/streams/latest/dev/kcl-migration-from-2-3.html) | | workerMetricsReady | 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/streams/latest/dev/kcl-migration-from-2-3.html) | 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_2X`Wenn 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.](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py)