Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Migrer de KCL 2.x vers KCL 3.x

Cette rubrique fournit des instructions détaillées pour migrer votre client de KCL 2.x vers KCL 3.x. Nous vous recommandons de migrer vers KCL 3.5 ou une version ultérieure pour utiliser le format de tableau unique. KCL 3.x prend en charge la migration sur place des consommateurs KCL 2.x. Vous pouvez continuer à consommer les données de votre flux de données Kinesis tout en faisant migrer vos employés de manière continue.

Étape 1 : Prérequis

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

Étape 2 : ajouter des dépendances

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

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

Vous pouvez rechercher la dernière version de la KCL sur le référentiel central de 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 :

configsBuilder.coordinatorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X_PHASE1)

Au cours de cette phase, votre application reste compatible avec KCL 2.x et la migration ne démarre pas, ce qui vous permet de déployer en toute sécurité la bibliothèque KCL 3.x sur l'ensemble de votre parc.

Une fois que tous les travailleurs ont exécutéCLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X_PHASE1, définissez cette configuration CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X sur pour démarrer la migration. Pour définir cette configuration, ajoutez la ligne suivante lors de la création de votre objet de planification :

configsBuilder.coordinatorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X)

L'exemple suivant montre comment configurer le paramètre 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.coordinatorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X),
    configsBuilder.leaseManagementConfig(),
    configsBuilder.lifecycleConfig(),
    configsBuilder.metricsConfig(),
    configsBuilder.processorConfig(),
    configsBuilder.retrievalConfig()
);

Il est important que tous les travailleurs 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 programmes de travail avec des algorithmes d'équilibrage de charge différents peut entraîner une distribution de charge sous-optimale car les deux algorithmes fonctionnent indépendamment.

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 travailleurs 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é KCL 3.x complet et commence à utiliser un nouvel algorithme d'équilibrage de charge KCL 3.x pour tous les travailleurs en cours d'exécution.

Étape 4 : Suivez les meilleures pratiques pour la mise en œuvre de la méthode shutdownRequested ()

KCL 3.x introduit une fonctionnalité appelée transfert gracieux des contrats de location afin de minimiser le retraitement des données lorsqu'un contrat de location est transféré à un autre collaborateur dans le cadre du processus de réattribution du bail. Pour ce faire, cochez le dernier numéro de séquence traité dans la table des contrats de location avant le transfert du contrat de location. Pour garantir le bon fonctionnement de la transmission gracieuse du bail, 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.

/**
 * 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 prérequis de KCL 3.x pour la collecte des métriques des collaborateurs

KCL 3.x collecte des mesures d'utilisation du processeur, telles que l'utilisation du processeur par les travailleurs, afin d'équilibrer la charge entre les travailleurs de manière uniforme. Les utilisateurs d'applications grand public peuvent exécuter 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)

Amazon Elastic Container Service (Amazon ECS) sur Amazon EC2

Amazon ECS sur AWS Fargate

Amazon Elastic Kubernetes Service (Amazon EKS) sur Amazon EC2

Amazon EKS sur AWS Fargate

É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 grand public 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.

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

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

É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. Une fois que 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 des baux en fonction de l'utilisation des ressources des travailleurs. Pour plus de détails sur le nouvel algorithme d'attribution de bail, consultezComment KCL attribue des baux aux travailleurs et équilibre la charge.

Pendant le déploiement, vous pouvez surveiller le processus de migration à l'aide des métriques suivantes envoyées à CloudWatch. Vous pouvez surveiller les indicateurs relatifs à l'Migrationopération. Toutes les métriques sont par KCL-application métrique et définies au niveau 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.

KCL fournit une capacité de restauration vers le mode compatible 2.x pendant la migration. Une fois la migration vers KCL 3.x réussie, 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.