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 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 pour Java 2. x
+ Maven ou Gradle pour la gestion des dépendances
**Important**
N'utilisez pas les AWS SDK pour 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 pour 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.
```
software.amazon.kinesis
amazon-kinesis-client
3.x.x
```
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](https://search.maven.org/artifact/software.amazon.kinesis/amazon-kinesis-client).
## É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.](https://docs.aws.amazon.com/streams/latest/dev/troubleshooting-consumers.html#compiliation-error-leasemanagementconfig) Nous vous recommandons de l'utiliser `ConfigsBuilder` pour définir les configurations KCL. `ConfigsBuilder`fournit 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'`checkpointer`objet dans la `shutdownRequested` méthode de votre classe. `RecordProcessor` Si vous n'invoquez pas l'`checkpointer`objet 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 la charge entre les travailleurs de manière uniforme. Les utilisateurs d'applications grand public peuvent exécuter des 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 [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)dans votre instance EC2.
**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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ec2-metadata.html).
+ 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4-fargate.html). 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 parvient 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](kcl-dynamoDB.md#kcl-assign-leases).
## É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](kcl-iam-permissions.md).
**Important**
Il est possible que les actions et ressources IAM suivantes ne soient pas ajoutées à vos applications KCL existantes dans la stratégie 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`,`DescribeTable`,`Scan`,`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](https://docs.aws.amazon.com/streams/latest/dev/troubleshooting-consumers.html#compilation-error-leasemanagementconfig) 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, consultez[Comment KCL attribue les baux aux travailleurs et équilibre la charge](kcl-dynamoDB.md#kcl-assign-leases).
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'`Migration`opé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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/streams/latest/dev/kcl-migration-from-2-3.html) |
| 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/streams/latest/dev/kcl-migration-from-2-3.html) |
| 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/streams/latest/dev/kcl-migration-from-2-3.html) |
| 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/streams/latest/dev/kcl-migration-from-2-3.html) |
| 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/streams/latest/dev/kcl-migration-from-2-3.html) |
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](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py).