software.amazon.kinesis.coordinator.migration

Enum TableMigrationStatus

java.lang.Object

java.lang.Enum<TableMigrationStatus>

software.amazon.kinesis.coordinator.migration.TableMigrationStatus

All Implemented Interfaces:

Serializable, Comparable<TableMigrationStatus>

public enum TableMigrationStatus
extends Enum<TableMigrationStatus>

TableMigration support during upgrade from KCLv3.4 or lower to KCLv3.5 or higher.

Table migration follows a 2-phase deployment to consolidate CoordinatorState and WorkerMetricStats from separate DDB tables into the Lease table:

• Phase 1: Upgrade to KCLv3.5+ with default config (CoordinatorConfig#migrateAllEntitiesToLeaseTable() = false). Workers emit a min support code in WorkerMetricStats to signal readiness.
• Phase 2: Deploy KCLv3.5+ with CoordinatorConfig#migrateAllEntitiesToLeaseTable() = true. Workers switch to writing all entities (WorkerMetricStats, CoordinatorState) to the Lease table.

This enum is persisted in storage, so any changes to it need to be backward compatible. Reorganizing the values is not backward compatible; if versions are removed, the corresponding enum value cannot be reused without backward compatibility considerations.

DDB State Transitions (3.4x → 3.5x table migration):

                                                  3.4x -> 3.5x Table Migration
   .------------------------------------------------------------------------------------------------------------------.
   | .-----------------------.-----------------------------.  .-------------------------------.                       |
   | |                       ^   min support code          |  |     code rollback             |                       |
   | |                       |   not met due to rollback   |  |                               |                       |
   | V                       |   (Best effort)             |  V                               |                       V
 Start ------------------> INIT -----------------------> DEPLOYED -----------------------> PENDING ---------------> COMPLETE
        Phase 1                     Bake time                      Phase 2 deployment                Bake time
        deployment                                                 (migrateAllEntitiesToLeaseTable   (configured via
        Leader writes INIT                                          = true)                          tableMigrationCompleteBakeTimeSeconds)
        when all workers                                           Leader writes PENDING when
        emit min support code                                      all workers emit to lease table
        in WorkerMetricStats                                       and CoordinatorState entries
                                                                   are moved to Lease table

 

There is local state workers use and there is a global state that the leader manages as a TableMigrationState which is a CoordinatorState entry in DDB.

See Also:

TableMigrationStateMachineImpl, CoordinatorConfig#migrateAllEntitiesToLeaseTable()

Enum Constant Summary

Enum Constants

Enum Constant and Description
TABLE_MIGRATION_STATUS_COMPLETE This status indicates that table migration is complete.
TABLE_MIGRATION_STATUS_DEPLOYED This state in DDB signifies all workers are emitting min support code in the Worker metric stats steadily for the bake time and the application is ready to move on to phase 2 deployment.
TABLE_MIGRATION_STATUS_INIT This state in the DDB signifies all workers are emitting min support code in WorkerMetricStats and the bake time to move to DEPLOYED has started.
TABLE_MIGRATION_STATUS_PENDING This state in DDB signifies, all workers have been deployed with phase 2 cofiguration and have switched writing to workerMetricStats into lease table and the leader has moved over all other coordinatorState entries from legacy table to the lease table.
TABLE_MIGRATION_STATUS_UNKNOWN This is a local state before table migration status is either determined by reading the DDB status and the KCL configuration.

Method Summary

Modifier and Type	Method and Description
long	getBakeTimeSeconds(Map<TableMigrationStatus,Long> overrides)
static TableMigrationStatus	valueOf(String name) Returns the enum constant of this type with the specified name.
static TableMigrationStatus[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

TABLE_MIGRATION_STATUS_UNKNOWN

public static final TableMigrationStatus TABLE_MIGRATION_STATUS_UNKNOWN

This is a local state before table migration status is either determined by reading the DDB status and the KCL configuration.

TABLE_MIGRATION_STATUS_INIT

public static final TableMigrationStatus TABLE_MIGRATION_STATUS_INIT

This state in the DDB signifies all workers are emitting min support code in WorkerMetricStats and the bake time to move to DEPLOYED has started. Worker enter this state locally in phase1 deployment. In this local state workers emit min support code in WorkerMetricStats which is written to legacy table, but reads for WorkerMetricStats and CoordinatorState will be merged from both legacy and lease table.

TABLE_MIGRATION_STATUS_DEPLOYED

public static final TableMigrationStatus TABLE_MIGRATION_STATUS_DEPLOYED

This state in DDB signifies all workers are emitting min support code in the Worker metric stats steadily for the bake time and the application is ready to move on to phase 2 deployment. Worker enter this state locally when the ddb state transitions to it. In terms of functionality there is no difference, between INIT and DEPLOYED workers continue to emit min support code in WorkerMetricStats into legacy table and read WorkerMetricStats and CoordinatorState from both legacy and lease table.

TABLE_MIGRATION_STATUS_PENDING

public static final TableMigrationStatus TABLE_MIGRATION_STATUS_PENDING

This state in DDB signifies, all workers have been deployed with phase 2 cofiguration and have switched writing to workerMetricStats into lease table and the leader has moved over all other coordinatorState entries from legacy table to the lease table. This is when bake time to move to COMPLETE state starts. Locally this state is entered when phase 2 code is deployed and this indicates to workers to switch to writing all entities into lease table. In this local state workers continue to emit min support code in WorkerMetricStats written to lease table, and reads for WorkerMetricStats and CoordinatorState will from both legacy and lease table. This state allows rollback to DEPLOYED if the workers rollback to phase1 deployment and switch to writing entities to the corresponding table again.

TABLE_MIGRATION_STATUS_COMPLETE

public static final TableMigrationStatus TABLE_MIGRATION_STATUS_COMPLETE

This status indicates that table migration is complete. All workers will always use the lease table for all entities for both reads and writes. There is no rollback allowed once the status is COMPLETE. The bake time for this final step can be configured using CoordinatorConfig#tableMigrationCompleteBakeTimeSeconds().

Method Detail

values

public static TableMigrationStatus[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (TableMigrationStatus c : TableMigrationStatus.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static TableMigrationStatus valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

getBakeTimeSeconds

public long getBakeTimeSeconds(Map<TableMigrationStatus,Long> overrides)