# Migración a un formato de tabla única para KCL 3.5.x\+
A partir de KCL 3.5, puede consolidar todos los metadatos de DynamoDB en una sola tabla de concesiones con el **formato de tabla única**. De forma predeterminada, KCL 3.x crea tres tablas de DynamoDB para cada aplicación: la tabla de concesiones, la tabla de métricas de procesos de trabajo y la tabla de estado de coordinadores. El formato de tabla única reduce estas tres tablas a una, lo que ayuda a evitar los límites de tablas por cuenta de DynamoDB.
## Cómo funciona el formato de tabla única
En formato de tabla única, KCL almacena las métricas de los trabajadores y las entradas del estado del coordinador en la tabla de concesiones junto con las entradas de concesión. Cada elemento incluye un atributo `entityType` que distingue entre los distintos tipos de registro.
Las métricas de los trabajadores y los elementos del estado del coordinador utilizan la misma estructura de clave principal que la tabla de concesiones, pero incluyen un valor `entityType` distinto. Este atributo permite a KCL identificar el propósito de cada elemento durante los análisis de la tabla.
Cada componente de KCL filtra las entradas que necesita para su lógica empresarial en función del atributo `entityType`. Por ejemplo, el administrador de asignaciones de arrendamientos (LAM) filtra las entradas de métricas de concesiones y trabajadores para realizar la asignación de concesiones.
## Configuración del formato de tabla única
La forma de habilitar el formato de tabla única depende de la versión actual de KCL:
+ **Si utiliza KCL 2.x:** siga la guía de migración actualizada para actualizar a KCL 3.5. El formato de tabla única se utiliza de forma predeterminada para las nuevas migraciones de 2.x a 3.5.
+ **Si utiliza KCL 3.0-3.4:** debe realizar una implementación en dos fases para migrar al formato de tabla única. Consulte los siguientes pasos de configuración y migración.
Para los clientes actuales de KCL 3.x, defina la opción de configuración `migrateAllEntitiesToLeaseTable` en `CoordinatorConfig`. Esta opción controla si KCL almacena todos los tipos de entidades de metadatos en la tabla de concesiones.
**Valores de configuración para `migrateAllEntitiesToLeaseTable`**
| Valor | Predeterminado | Efecto |
| --- | --- | --- |
| false | Sí | KCL utiliza tablas independientes para las métricas de los trabajadores y el estado del coordinador. El código de la aplicación admite el formato de tabla única, pero no lo activa. |
| true | No | KCL comienza a escribir las métricas de los trabajadores y los datos del estado del coordinador en la tabla de concesiones. Establezca este valor en la implementación de la fase 2 después de que `TableMigrationStatus` alcance `DEPLOYED` y haya verificado que no hay regresiones. |
La migración de KCL 3.x a un formato de tabla única requiere una implementación en dos fases:
1. **Fase 1:** implemente el código KCL 3.5 actualizado con `migrateAllEntitiesToLeaseTable` establecido en `false` (el valor predeterminado). Esto instala el nuevo código que admite el formato de tabla única, pero no activa la migración.
1. **Fase 2:** una vez que todos los trabajadores ejecuten el nuevo código y `TableMigrationStatus` alcance `DEPLOYED`, y haya comprobado que no hay regresiones, vuelva a implementarlo con `migrateAllEntitiesToLeaseTable` establecido en `true` para iniciar la migración.
## Estados de migración
`TableMigrationStateMachine` administra la transición del formato de varias tablas al formato de una sola tabla. KCL rastrea el estado actual de la migración en una entrada independiente de estados coordinadores llamada `TableMigration3.5` en la tabla de estados coordinadores. Para ver la lista completa de estados, transiciones y descripciones, consulte los [estados de migración de una sola tabla de KCL](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java) en el sitio web de GitHub.
**Estados de migración en formato de tabla única**
| Estado | Descripción | Condición de transición |
| --- | --- | --- |
| INIT | Estado inicial. Todos los trabajadores emiten el código de soporte mínimo en las estadísticas de métricas de los trabajadores. Los trabajadores siguen emitiendo las métricas de los trabajadores en la tabla heredada y leyendo las métricas de los trabajadores y el estado del coordinador en las tablas heredadas y en las de concesiones. Desde el punto de vista funcional, no hay diferencia entre INIT y DEPLOYED. | Todos los trabajadores emiten el código de soporte mínimo de forma constante durante el tiempo de incorporación. La aplicación está lista para pasar a la fase 2 de implementación. |
| DEPLOYED | Se ha implementado a todos los trabajadores con el nuevo código (fase 1 completada). La aplicación admite el formato de tabla única, pero no lo ha activado. | La implementación de la fase 2 comienza con `migrateAllEntitiesToLeaseTable` configurado en `true`. |
| PENDING | Todos los trabajadores ejecutan el nuevo código. KCL migra los datos de las tablas de métricas de los trabajadores y de estado de los coordinadores a la tabla de concesiones. | Una vez finalizada la migración, transcurre un tiempo de incorporación predeterminado de 24 horas. |
| COMPLETE | La migración se ha completado. KCL utiliza la tabla de concesiones exclusivamente para todas las lecturas y escrituras. Las antiguas tablas de métricas de los trabajadores y de estado de los coordinadores ya no se utilizan. | Estado de terminal. No se producen más transiciones. |
Para obtener información detallada sobre cada estado, las condiciones de transición y el comportamiento completo de la máquina de estados, consulte la [máquina de estados de migración de tabla única de KCL](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java) en el sitio web de GitHub.
**nota**
El tiempo de incorporación predeterminado entre los estados PENDING y COMPLETE es de 24 horas, pero puede configurarlo hasta una semana. Durante este periodo, KCL utiliza la tabla de concesiones para todas las lecturas y escrituras, pero no elimina las tablas antiguas. Debe eliminar manualmente las tablas antiguas de métricas de los trabajadores y estados de los coordinadores después de confirmar que la migración se ha realizado correctamente. KCL no elimina estas tablas automáticamente.
## Métricas de migración
Con KCL, puede supervisar el progreso y el estado de la migración de tabla única mediante métricas de CloudWatch. Utilice estas métricas para confirmar que los trabajadores han adoptado el nuevo código y para realizar un seguimiento de la migración a medida que avanza por sus estados. También puede detectar errores de lectura, escritura o eliminación de DynamoDB durante la migración. En las tablas siguientes, se agrupan las métricas por la operación de KCL (dimensión métrica) que las emite y por el momento en que se emite cada métrica.
El trabajador líder elegido emite continuamente las siguientes métricas, independientemente de si se está realizando una migración:
**Métricas emitidas por el líder en todo momento**
| Operación | Métrica | Unidad | Descripción |
| --- | --- | --- | --- |
| `TableMigration` | `StatusOrdinal` | Ninguno | Ordinal del estado de migración actual de DynamoDB: `0` = UNKNOWN, `1` = INIT, `2` = DEPLOYED, `3` = PENDING, `4` = COMPLETE. |
| `WorkerMetrics` | `FleetMinSupportCode` | Ninguno | Código de soporte mínimo para todos los trabajadores propietarios de concesiones de la flota. |
El trabajador líder elegido emite las siguientes métricas solo mientras se está realizando una migración:
**Métricas emitidas por el líder durante la migración**
| Operación | Métrica | Unidad | Descripción |
| --- | --- | --- | --- |
| `TableMigration` | `Phase1Worker` | Recuento | Número de trabajadores que admiten trabajar con una sola tabla de DynamoDB, pero que aún no han migrado para usar la tabla única. |
| `TableMigration` | `Phase2Worker` | Recuento | Número de trabajadores que han migrado a escribir en una sola tabla. Es posible que estos trabajadores sigan leyendo en varias tablas hasta que se complete la migración de tablas. |
| `TableMigration` | `PrePhase1Worker` | Recuento | Número de trabajadores de una versión anterior a 3.5 que no admiten el funcionamiento en una sola tabla de DynamoDB. |
| `TableMigration` | `WriteFault` | Recuento | `1` en caso de error de escritura en DynamoDB, `0` en caso de éxito. |
| `TableMigration` | `DeleteFault` | Recuento | `1` en caso de error de eliminación en DynamoDB, `0` en caso de éxito. |
| `TableMigration` | `CompletionFault` | Recuento | `1` si se produce un error en la escritura transaccional del estado `COMPLETE`, `0` en caso de éxito. |
| `TableMigrationAsyncMove` | `Success` | Recuento | `1` en caso de un movimiento transaccional exitoso de las entradas de CoordinatorState, `0` en caso de error. |
| `TableMigrationAsyncMove` | `Time` | Milisegundos | Duración de la operación de movimiento asíncrono. |
| `TableMigrationAsyncMove` | `BatchCount` | Recuento | Número de lotes que se movieron correctamente. |
Todos los trabajadores emiten las siguientes métricas mientras se está realizando una migración:
**Métricas emitidas por todos los trabajadores durante la migración**
| Operación | Métrica | Unidad | Descripción |
| --- | --- | --- | --- |
| `TableMigration` | `ReadFault` | Recuento | `1` en caso de error al leer el `TableMigrationState` de DynamoDB, `0` en caso de éxito. |
| `TableMigration` | `Time` | Milisegundos | Duración del funcionamiento de la máquina de estados. |
| `TableMigrationInitialize` | `Success` | Recuento | `1` si la inicialización es correcta, `0` si se produce un error. |
| `TableMigrationInitialize` | `Time` | Milisegundos | Duración de la operación de inicialización. |
Utilice estas métricas para decidir cuándo avanzar en la migración. Cuando `StatusOrdinal` es coherente `2` (DEPLOYED) y `PrePhase1Worker` es `0`, todos los trabajadores admiten el formato de tabla única y se puede pasar a la fase 2 de la implementación de la migración de tablas. Cuando `StatusOrdinal` alcanza `4` (COMPLETE), puede eliminar de forma segura las tablas antiguas.
## Consideraciones de restauración
La compatibilidad con la reversión depende del `TableMigrationStatus` actual:
+ **Durante la fase 1** (`TableMigrationStatus` es `DEPLOYED` o no está configurado): puede volver a la versión anterior de forma segura. El nuevo código se ejecuta en un modo compatible con versiones anteriores y no se ha escrito ningún dato en las entradas que no son de concesión en la tabla de concesiones.
+ **Durante la fase 2** (`TableMigrationStatus` es `DEPLOYED` o `PENDING`): puede volver a la fase 1. Los trabajadores vuelven a utilizar las tablas antiguas (formato de varias tablas) para las métricas de los trabajadores y el estado del coordinador. La migración se ha deshecho.
+ **Tras el estado COMPLETE**: no se admite la reversión. KCL solo usa la tabla de concesiones para todas las entidades. Incluso si el código vuelve a la fase 1, el trabajador sigue utilizando la tabla de concesiones para todas las entidades y se ignora la configuración.
**aviso**
Una vez que la migración alcanza el estado COMPLETE, la aplicación funciona exclusivamente en el modo de tabla única. Se omite la configuración `migrateAllEntitiesToLeaseTable` y KCL no vuelve a utilizar tablas independientes. Asegúrese de que el tiempo de incorporación antes de pasar a COMPLETE sea suficiente, ya que después de eso, ni siquiera una reversión de código volverá a usar varias tablas.
## Prácticas recomendadas
Siga estas prácticas recomendadas al adoptar el formato de tabla única:
+ Tras la fase 1 de la implementación, compruebe que la entrada del estado de coordinador `TableMigration3.5` alcance el estado `DEPLOYED`. Asegúrese de que no haya regresiones antes de pasar a la fase 2.
+ Supervise el `TableMigrationStatus` en la entrada del estado del coordinador de `TableMigration3.5` para hacer un seguimiento del progreso en los estados DEPLOYED, PENDING y COMPLETE. El estado se almacena en la tabla de estados del coordinador como una entrada independiente (no en la tabla de concesiones) hasta que la migración alcanza el estado COMPLETE.
+ Asegúrese de que el tiempo de incorporación antes de pasar a COMPLETE sea suficiente, ya que después de eso, ni siquiera una reversión de código volverá a usar varias tablas. La aplicación solo funciona en el modo de tabla única.
+ Después de que la migración alcance el estado COMPLETE, elimine manualmente las tablas antiguas de métricas de los trabajadores y estados de los coordinadores. KCL no elimina estas tablas automáticamente, solo deja de usarlas.
+ Si ha configurado `CoordinatorConfig.coordinatorStateTableConfig` o `LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig`, puede eliminar estas configuraciones una vez finalizada la migración. Estas configuraciones están en desuso en KCL 3.5 y versiones posteriores.