View a markdown version of this page

Format de table unique pour KCL - Amazon Kinesis Data Streams
Comment fonctionne le format de tableau uniqueConfiguration d'un format de tableau uniqueÉtats migratoiresConsidérations relatives à l'annulationBonnes pratiques

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.

Format de table unique pour KCL

À partir de KCL 3.5, vous pouvez consolider toutes les métadonnées DynamoDB dans une seule table de location en utilisant le format de table unique. Par défaut, KCL 3.x crée trois tables DynamoDB pour chaque application : la table des baux, la table des métriques des travailleurs et la table des états des coordinateurs. Le format de table unique réduit ces trois tables à une seule, ce qui vous permet d'éviter les limites de tables DynamoDB au niveau du compte.

Comment fonctionne le format de tableau unique

Dans un format de tableau unique, KCL stocke les indicateurs des employés et les entrées d'état des coordinateurs dans le tableau des baux à côté des entrées de bail. Chaque élément inclut un entityType attribut qui fait la distinction entre les différents types d'enregistrement.

Les indicateurs relatifs aux travailleurs et les éléments relatifs à l'état du coordinateur utilisent la même structure de clé primaire que le tableau des baux, mais incluent une entityType valeur distincte. Cet attribut permet à KCL d'identifier l'objectif de chaque élément lors de l'analyse des tables.

Chaque composant de KCL filtre les entrées dont il a besoin pour sa logique métier en fonction de l'entityTypeattribut. Par exemple, le Lease Assignment Manager (LAM) filtre les entrées de mesures relatives aux baux et aux travailleurs pour effectuer l'attribution des baux.

Configuration d'un format de tableau unique

La manière dont vous activez le format de tableau unique dépend de votre version actuelle de KCL :

  • Si vous utilisez KCL 2.x : suivez le guide de migration mis à jour pour passer à KCL 3.5. Le format de table unique est utilisé par défaut pour les nouvelles migrations de la version 2.x vers la version 3.5.

  • Si vous utilisez KCL 3.0—3.4 : vous devez effectuer un déploiement en deux phases pour migrer vers un format de table unique. Consultez les étapes de configuration et de migration suivantes.

Pour les clients KCL 3.x existants, définissez l'option de migrateAllEntitiesToLeaseTable configuration dans. CoordinatorConfig Cette option contrôle si KCL stocke tous les types d'entités de métadonnées dans la table des baux.

Valeurs de configuration pour la migration AllEntitiesToLeaseTable
Value Par défaut Effet
false Oui

KCL utilise des tables distinctes pour les métriques des travailleurs et l'état du coordinateur. Le code de l'application prend en charge le format de table unique mais ne l'active pas.
true Non

KCL commence à écrire les métriques des travailleurs et les données sur l'état des coordinateurs dans le tableau des baux. Définissez cette valeur sur le déploiement de la phase 2 une fois que vous aurez TableMigrationStatus atteint les objectifs DEPLOYED et que vous n'aurez aucune régression.

La migration de KCL 3.x vers le format de table unique nécessite un déploiement en deux phases :

  1. Phase 1 : Déployez le code KCL 3.5 mis à jour avec la valeur migrateAllEntitiesToLeaseTable définie sur false (valeur par défaut). Cela installe le nouveau code qui prend en charge le format de table unique mais n'active pas la migration.

  2. Phase 2 : une fois que tous les opérateurs ont exécuté le nouveau code et les TableMigrationStatus portéesDEPLOYED, et que vous avez vérifié qu'il n'y a pas de régressions, redéployez avec migrateAllEntitiesToLeaseTable set true to pour commencer la migration.

États migratoires

TableMigrationStateMachineGère la transition du format multi-tables au format de table unique. KCL suit l'état actuel de la migration dans une entrée d'état de coordinateur distincte appelée TableMigration3.5 dans la table des états des coordinateurs. Pour la liste complète des états, des transitions et des descriptions, voir États de migration à table unique KCL.

États de migration au format de tableau unique
State Description Condition de transition
INIT

État initial. Tous les travailleurs émettent le code de support minimum dans les statistiques métriques des travailleurs. Les travailleurs continuent à saisir les indicateurs relatifs aux employés dans l'ancienne table et à lire les indicateurs des travailleurs et l'état des coordinateurs à partir des tables existantes et des baux. Sur le plan fonctionnel, il n'y a aucune différence entre INIT et DEPLOYED.

Tous les travailleurs émettent régulièrement le code de support minimum pendant le temps de cuisson. L'application est prête à passer au déploiement de phase 2.
DEPLOYED

Tous les travailleurs ont été déployés avec le nouveau code (phase 1 terminée). L'application prend en charge le format de tableau unique mais ne l'a pas activé.

Le déploiement de la phase 2 commence par une migrateAllEntitiesToLeaseTable valeur définie surtrue.
PENDING

Tous les travailleurs exécutent le nouveau code. KCL migre les données des statistiques des travailleurs et des tables d'état des coordinateurs vers la table des baux.

Un temps de cuisson par défaut de 24 heures s'écoule une fois la migration terminée.
COMPLETE

La migration est terminée. KCL utilise la table des baux exclusivement pour toutes les lectures et écritures. Les anciennes métriques des travailleurs et les tables d'état des coordinateurs ne sont plus utilisées.

État du terminal. Aucune autre transition ne se produit.

Pour des informations détaillées sur chaque état, les conditions de transition et le comportement complet de la machine à états, voir Machine à états de migration à table unique KCL.

Note

Le temps de cuisson par défaut entre les états PENDING et COMPLETE est de 24 heures, mais vous pouvez le configurer jusqu'à une semaine. Pendant cette période, KCL utilise la table des baux pour toutes les lectures et écritures, mais ne supprime pas les anciennes tables. Vous devez supprimer manuellement les anciens indicateurs de travail et les tables d'état des coordinateurs une fois que vous avez confirmé la réussite de la migration. KCL ne supprime pas ces tables automatiquement.

Considérations relatives à l'annulation

La prise en charge du rollback dépend du courant TableMigrationStatus :

  • Pendant la phase 1 (TableMigrationStatusdéfinie DEPLOYED ou pas encore définie) : vous pouvez revenir à la version précédente en toute sécurité. Le nouveau code s'exécute en mode rétrocompatible et aucune donnée n'a été écrite dans les entrées autres que les baux de la table des baux.

  • Pendant la phase 2 (TableMigrationStatusc'est DEPLOYED ouPENDING) : vous pouvez revenir à la phase 1. Les travailleurs recommencent à utiliser les anciens tableaux (format multi-tables) pour les indicateurs des travailleurs et l'état des coordinateurs. La migration est annulée.

  • Une fois l'état TERMINÉ : le rollback n'est pas pris en charge. KCL utilise uniquement la table des baux pour toutes les entités. Même si le code revient à la phase 1, le travailleur continue d'utiliser la table des baux pour toutes les entités et la configuration est ignorée.

Avertissement

Une fois que la migration atteint l'état COMPLET, l'application fonctionne exclusivement en mode table unique. La migrateAllEntitiesToLeaseTable configuration est ignorée et KCL ne recommence pas à utiliser des tables séparées. Assurez-vous que le temps de cuisson avant de passer à COMPLETE est suffisant, car après cela, même une restauration du code ne permet pas de revenir à plusieurs tables.

Bonnes pratiques

Suivez ces bonnes pratiques lorsque vous adoptez un format de tableau unique :

  • Après le déploiement de la phase 1, vérifiez que l'entrée d'état du coordinateur TableMigration3.5 atteint DEPLOYED le statut. Assurez-vous qu'il n'y a pas de régressions avant de passer à la phase 2.

  • Surveillez l'entrée TableMigrationStatus dans l'état TableMigration3.5 coordinateur pour suivre la progression dans les états DÉPLOYÉ, EN ATTENTE et COMPLET. Le statut est enregistré dans la table d'état du coordinateur sous forme d'entrée séparée (pas dans la table des baux) jusqu'à ce que la migration soit terminée.

  • Assurez-vous que le temps de cuisson avant de passer à COMPLETE est suffisant, car après cela, même une restauration du code ne permet pas de revenir à plusieurs tables. L'application fonctionne uniquement en mode table unique.

  • Une fois la migration terminée, supprimez manuellement les anciens indicateurs de travail et les tables d'état des coordinateurs. KCL ne supprime pas ces tables automatiquement ; il cesse simplement de les utiliser.

  • Si vous avez configuré CoordinatorConfig.coordinatorStateTableConfig ouLeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig, vous pouvez supprimer ces configurations une fois la migration terminée. Ces configurations sont déconseillées dans KCL 3.5 et versions ultérieures.