Migrer de KCL 2.x vers KCL 3.x

Cette rubrique fournit des step-by-step instructions pour faire migrer votre client de KCL 2.x vers KCL 3.x. KCL 3.x prend en charge la migration sur place des utilisateurs de KCL 2.x. Vous pouvez continuer à utiliser les données de votre flux de données Kinesis tout en faisant migrer vos employés de manière progressive.

Important

KCL 3.x conserve les mêmes interfaces et méthodes que KCL 2.x. Il n'est donc pas nécessaire de mettre à jour votre code de traitement des enregistrements pendant la migration. Cependant, vous devez définir la configuration appropriée et vérifier les étapes requises pour la migration. Nous vous recommandons vivement de suivre les étapes de migration suivantes pour une expérience de migration fluide.

Étape 1 : Prérequis

Avant de commencer à utiliser KCL 3.x, assurez-vous que vous disposez des éléments suivants :

• Kit de développement Java (JDK) 8 ou version ultérieure

• AWS SDK for Java 2. x

• Maven ou Gradle pour la gestion des dépendances

Important

N'utilisez pas les AWS SDK for Java versions 2.27.19 à 2.27.23 avec KCL 3.x. Ces versions incluent un problème qui provoque une erreur d'exception liée à l'utilisation de DynamoDB par KCL. Nous vous recommandons d'utiliser la AWS SDK for Java version 2.28.0 ou ultérieure pour éviter ce problème.

Étape 2 : ajouter des dépendances

Si vous utilisez Maven, ajoutez la dépendance suivante à votre pom.xml fichier. Assurez-vous d'avoir remplacé la version 3.x.x par la dernière version de KCL.

<dependency>
    <groupId>software.amazon.kinesis</groupId>
    <artifactId>amazon-kinesis-client</artifactId>
    <version>3.x.x</version> <!-- Use the latest version -->
</dependency>

Si vous utilisez Gradle, ajoutez ce qui suit à votre build.gradle fichier. Assurez-vous d'avoir remplacé la version 3.x.x par la dernière version de KCL.

implementation 'software.amazon.kinesis:amazon-kinesis-client:3.x.x'

Vous pouvez vérifier la dernière version de la KCL dans le référentiel central Maven.

Étape 3 : Configuration de la configuration liée à la migration

Pour migrer de KCL 2.x vers KCL 3.x, vous devez définir le paramètre de configuration suivant :

• CoordinatorConfig. clientVersionConfig: Cette configuration détermine le mode de compatibilité des versions de KCL dans lequel l'application s'exécutera. Lors de la migration de KCL 2.x vers 3.x, vous devez définir cette configuration sur. CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X Pour définir cette configuration, ajoutez la ligne suivante lors de la création de votre objet planificateur :

configsBuilder.coordiantorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPLATIBLE_WITH_2X)

Voici un exemple de la façon de définir le CoordinatorConfig.clientVersionConfig pour la migration de KCL 2.x vers 3.x. Vous pouvez ajuster d'autres configurations selon vos besoins spécifiques :

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()
);

Il est important que tous les utilisateurs de votre application grand public utilisent le même algorithme d'équilibrage de charge à un moment donné, car KCL 2.x et 3.x utilisent des algorithmes d'équilibrage de charge différents. L'exécution de travailleurs utilisant des algorithmes d'équilibrage de charge différents peut entraîner une distribution de charge sous-optimale, car les deux algorithmes fonctionnent indépendamment les uns des autres.

Ce paramètre de compatibilité KCL 2.x permet à votre application KCL 3.x de s'exécuter dans un mode compatible avec KCL 2.x et d'utiliser l'algorithme d'équilibrage de charge pour KCL 2.x jusqu'à ce que tous les utilisateurs de votre application grand public aient été mis à niveau vers KCL 3.x. Une fois la migration terminée, KCL passe automatiquement en mode de fonctionnalité complète de KCL 3.x et commence à utiliser un nouvel algorithme d'équilibrage de charge KCL 3.x pour tous les travailleurs en cours d'exécution.

Important

Si vous n'utilisez pas ConfigsBuilder mais créez un LeaseManagementConfig objet pour définir des configurations, vous devez ajouter un autre paramètre appelé applicationName dans la version 3.x ou ultérieure de KCL. Pour plus de détails, voir Erreur de compilation avec le LeaseManagementConfig constructeur. Nous vous recommandons de l'utiliser ConfigsBuilder pour définir les configurations KCL. ConfigsBuilderfournit une méthode plus flexible et plus facile à gérer pour configurer votre application KCL.

Étape 4 : Suivez les meilleures pratiques pour l'implémentation de la méthode ShutdownRequested ()

KCL 3.x introduit une fonctionnalité appelée transfert de bail progressif afin de minimiser le retraitement des données lorsqu'un bail est transféré à un autre travailleur dans le cadre du processus de réattribution du bail. Pour ce faire, il suffit de vérifier le dernier numéro de séquence traité dans le tableau des baux avant le transfert des baux. Pour garantir le bon fonctionnement du transfert de bail progressif, vous devez vous assurer d'invoquer l'checkpointerobjet dans la shutdownRequested méthode de votre classe. RecordProcessor Si vous n'invoquez pas l'checkpointerobjet dans la shutdownRequested méthode, vous pouvez l'implémenter comme illustré dans l'exemple suivant.

Important

• L'exemple de mise en œuvre suivant est une exigence minimale pour un transfert de bail harmonieux. Vous pouvez l'étendre pour inclure une logique supplémentaire liée au point de contrôle si nécessaire. Si vous effectuez un traitement asynchrone, assurez-vous que tous les enregistrements envoyés en aval ont été traités avant d'appeler le point de contrôle.

• Bien que le transfert progressif des baux réduise considérablement la probabilité de retraitement des données lors des transferts de bail, il n'élimine pas totalement cette possibilité. Pour préserver l'intégrité et la cohérence des données, concevez vos applications grand public en aval de manière à ce qu'elles soient idempotentes. Cela signifie qu'ils devraient être en mesure de traiter d'éventuels doublons d'enregistrements sans effets négatifs sur l'ensemble du système.

/**
 * 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);
    } 
}

Étape 5 : Vérifiez les conditions préalables à la KCL 3.x pour la collecte des métriques relatives aux travailleurs

KCL 3.x collecte des mesures d'utilisation du processeur, telles que l'utilisation du processeur, auprès des travailleurs afin d'équilibrer uniformément la charge entre les travailleurs. Les utilisateurs d'applications grand public peuvent exécuter leurs applications sur Amazon EC2, Amazon ECS, Amazon EKS ou AWS Fargate. KCL 3.x peut collecter des métriques d'utilisation du processeur auprès des travailleurs uniquement lorsque les conditions préalables suivantes sont remplies :

Amazon Elastic Compute Cloud(Amazon EC2)

• Votre système d'exploitation doit être Linux.

• Vous devez l'activer IMDSv2dans votre EC2 instance.

Amazon Elastic Container Service (Amazon ECS) sur Amazon EC2

• Votre système d'exploitation doit être Linux.

• Vous devez activer la version 4 du point de terminaison des métadonnées des tâches ECS.

• La version de votre agent de conteneur Amazon ECS doit être 1.39.0 ou ultérieure.

Amazon ECS sur AWS Fargate

• Vous devez activer la version 4 du point de terminaison des métadonnées des tâches Fargate. Si vous utilisez la version 1.4.0 ou ultérieure de la plateforme Fargate, cette option est activée par défaut.

• Version 1.4.0 ou ultérieure de la plateforme Fargate.

Amazon Elastic Kubernetes Service (Amazon EKS) sur Amazon EC2

• Votre système d'exploitation doit être Linux.

Amazon EKS sur AWS Fargate

• Plateforme Fargate 1.3.0 ou version ultérieure.

Important

Si KCL 3.x ne peut pas collecter les métriques d'utilisation du processeur auprès des travailleurs parce que les conditions préalables ne sont pas remplies, il rééquilibrera la charge en fonction du niveau de débit par bail. Ce mécanisme de rééquilibrage de secours garantira à tous les travailleurs des niveaux de débit total similaires grâce aux baux attribués à chaque travailleur. Pour de plus amples informations, veuillez consulter Comment KCL attribue les baux aux travailleurs et équilibre la charge.

Étape 6 : Mettre à jour les autorisations IAM pour KCL 3.x

Vous devez ajouter les autorisations suivantes au rôle ou à la politique IAM associé à votre application client KCL 3.x. Cela implique de mettre à jour la politique IAM existante utilisée par l'application KCL. Pour de plus amples informations, veuillez consulter Autorisations IAM requises pour les applications grand public KCL.

Important

Les actions et ressources IAM suivantes ne sont peut-être pas ajoutées à vos applications KCL existantes dans la politique IAM, car elles n'étaient pas nécessaires dans KCL 2.x. Assurez-vous de les avoir ajoutés avant d'exécuter votre application KCL 3.x :

• Mesures : UpdateTable

  • Ressources (ARNs) : arn:aws:dynamodb:region:account:table/KCLApplicationName

• Mesures : Query

  • Ressources (ARNs) : arn:aws:dynamodb:region:account:table/KCLApplicationName/Index/*

• Mesures :CreateTable, DescribeTableScan,GetItem,PutItem,UpdateItem, DeleteItem

  • Ressources (ARNs) :arn:aws:dynamodb:region:account:table/KCLApplicationName-WorkerMetricStats, arn:aws:dynamodb:region:account:table/KCLApplicationName-CoordinatorState

  Remplacez « région », « compte » et « KCLApplication nom » ARNs par votre propre Région AWS Compte AWS numéro et le nom de votre application KCL respectivement. Si vous utilisez des configurations pour personnaliser les noms des tables de métadonnées créées par KCL, utilisez les noms de table spécifiés au lieu du nom de l'application KCL.

Étape 7 : Déployez le code KCL 3.x auprès de vos employés

Après avoir défini la configuration requise pour la migration et rempli toutes les listes de contrôle de migration précédentes, vous pouvez créer et déployer votre code auprès de vos employés.

Note

Si vous constatez une erreur de compilation avec le LeaseManagementConfig constructeur, consultez la section Erreur de compilation avec le LeaseManagementConfig constructeur pour obtenir des informations de dépannage.

Étape 8 : terminer la migration

Pendant le déploiement du code KCL 3.x, KCL continue d'utiliser l'algorithme d'attribution de bail de KCL 2.x. Lorsque vous avez déployé avec succès le code KCL 3.x auprès de tous vos employés, KCL le détecte automatiquement et passe au nouvel algorithme d'attribution de bail en fonction de l'utilisation des ressources par les travailleurs. Pour plus de détails sur le nouvel algorithme d'attribution de bail, consultezComment KCL attribue les baux aux travailleurs et équilibre la charge.

Pendant le déploiement, vous pouvez surveiller le processus de migration à l'aide des métriques suivantes émises à CloudWatch. Vous pouvez surveiller les métriques dans le cadre de l'Migrationopération. Toutes les mesures sont per-KCL-application des mesures définies au niveau de la SUMMARY métrique. Si la Sum statistique de la CurrentState:3xWorker métrique correspond au nombre total de travailleurs dans votre application KCL, cela indique que la migration vers KCL 3.x s'est terminée avec succès.

Important

Il faut au moins 10 minutes à KCL pour passer au nouvel algorithme d'attribution des locataires une fois que tous les travailleurs sont prêts à l'exécuter.

CloudWatch métriques pour le processus de migration de KCL

Métriques	Description
CurrentState:3xWorker	Le nombre de travailleurs de KCL ayant migré avec succès vers KCL 3.x et exécutant le nouvel algorithme d'attribution de bail. Si le Sum nombre de cette métrique correspond au nombre total de vos travailleurs, cela indique que la migration vers KCL 3.x s'est terminée avec succès. Niveau de métrique : Summary Unités : nombre Statistiques : La statistique la plus utile est Sum
CurrentState:2xCompatibleWorker	Nombre de travailleurs KCL exécutés en mode compatible KCL 2.x pendant le processus de migration. Une valeur différente de zéro pour cette métrique indique que la migration est toujours en cours. Niveau de métrique : Summary Unités : nombre Statistiques : La statistique la plus utile est Sum
Fault	Le nombre d'exceptions rencontrées au cours du processus de migration. La plupart de ces exceptions sont des erreurs transitoires, et KCL 3.x réessaiera automatiquement de terminer la migration. Si vous observez une valeur de Fault métrique persistante, consultez vos journaux de la période de migration pour en savoir plus sur la résolution des problèmes. Si le problème persiste, contactez Support. Niveau de métrique : Summary Unités : nombre Statistiques : La statistique la plus utile est Sum
GsiStatusReady	État de la création de l'indice secondaire global (GSI) dans la table des baux. Cette métrique indique si le GSI de la table des baux a été créé, condition préalable à l'exécution de KCL 3.x. La valeur est 0 ou 1, 1 indiquant une création réussie. Lors d'un état de restauration, cette métrique ne sera pas émise. Une fois que vous aurez recommencé à avancer, vous pourrez reprendre le suivi de cette métrique. Niveau de métrique : Summary Unités : nombre Statistiques : La statistique la plus utile est Sum
workerMetricsReady	Le statut du travailleur mesure les émissions de tous les travailleurs. Les métriques indiquent si tous les travailleurs émettent des métriques telles que l'utilisation du processeur. La valeur est 0 ou 1, 1 indiquant que tous les travailleurs ont réussi à émettre des métriques et sont prêts pour le nouvel algorithme d'attribution de bail. Lors d'un état de restauration, cette métrique ne sera pas émise. Une fois que vous aurez recommencé à avancer, vous pourrez reprendre le suivi de cette métrique. Niveau de métrique : Summary Unités : nombre Statistiques : La statistique la plus utile est Sum

KCL fournit une fonctionnalité de restauration vers le mode compatible 2.x pendant la migration. Une fois la migration réussie vers KCL 3.x, nous vous recommandons de supprimer le CoordinatorConfig.clientVersionConfig paramètre « CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X si la restauration n'est plus nécessaire ». La suppression de cette configuration arrête l'émission de métriques liées à la migration depuis l'application KCL.

Note

Nous vous recommandons de surveiller les performances et la stabilité de votre application pendant un certain temps pendant la migration et une fois celle-ci terminée. Si vous constatez des problèmes, vous pouvez faire en sorte que les travailleurs utilisent les fonctionnalités compatibles avec KCL 2.x à l'aide de l'outil de migration KCL.