View a markdown version of this page

KCL 的单表格式 - Amazon Kinesis Data Streams
单表格式的工作原理配置单表格式迁移状态回滚注意事项最佳实践

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

KCL 的单表格式

从 KCL 3.5 开始，您可以使用单表格式将所有 DynamoDB 元数据整合到单个租赁表中。默认情况下，KCL 3.x 会为每个应用程序创建三个 DynamoDB 表：租赁表、工作器指标表和协调器状态表。单表格式将这三个表缩减为一个，这有助于您避免 DynamoDB 账户级别的表格限制。

单表格式的工作原理

在单表格式中，KCL 将工作人员指标和协调器状态条目与租赁条目一起存储在租赁表中。每个项目都包含一个entityType用于区分不同记录类型的属性。

工作器指标和协调器状态项使用与租赁表相同的主键结构，但包含不同的entityType值。此属性允许 KCL 在表格扫描期间识别每个项目的用途。

KCL 的每个组件都会根据entityType属性筛选出其业务逻辑所需的条目。例如，租赁分配管理器 (LAM) 筛选租赁和工作人员指标条目以执行租赁分配。

配置单表格式

如何启用单表格式取决于您当前的 KCL 版本：

  • 如果您使用的是 KCL 2.x：请按照更新的迁移指南升级到 KCL 3.5。默认情况下，从 2.x 到 3.5 的新迁移使用单表格式。

  • 如果您使用的是 KCL 3.0—3.4：必须执行两阶段部署才能迁移到单表格式。请参阅以下配置和迁移步骤。

对于现有的 KCL 3.x 客户，请在中设置migrateAllEntitiesToLeaseTable配置选项。CoordinatorConfig此选项控制 KCL 是否在租赁表中存储所有元数据实体类型。

迁移的配置值 AllEntitiesToLeaseTable
值 默认 效果
false 是

KCL 对工作器指标和协调器状态使用单独的表。应用程序代码支持单表格式，但不能将其激活。
true 否

KCL 开始将工作人员指标和协调器状态数据写入租赁表。TableMigrationStatus到达后在第 2 阶段部署上设置此值DEPLOYED，您就不会出现任何回归了。

从 KCL 3.x 迁移到单表格式需要分两个阶段进行部署：

  1. 第 1 阶段：部署更新后的 KCL 3.5 代码，migrateAllEntitiesToLeaseTable设置为false（默认）。这将安装支持单表格式但不会激活迁移的新代码。

  2. 第 2 阶段：在所有工作人员都运行新代码并TableMigrationStatus到达之后DEPLOYED，并且您已验证没有回归，请重新部署并migrateAllEntitiesToLeaseTable设置true为开始迁移。

迁移状态

TableMigrationStateMachine管理从多表格式到单表格式的过渡。KCL 在协调器状态表中调用的单独协调器状态条目TableMigration3.5中跟踪当前的迁移状态。有关状态、过渡和描述的完整列表，请参阅 KCL 单表迁移状态。

单表格式迁移状态
州 说明 过渡条件
INIT

初始状态。所有工作人员都在工作人员指标统计数据中发出最低支持代码。工作人员继续将工作人员指标发送到旧表中，并从旧表和租赁表中读取工作人员指标和协调器状态。从功能上讲，INIT 和 DEPLOYED 之间没有区别。

在烘焙时间内，所有工作人员都会稳定地发出最低支持代码。应用程序已准备好进入第 2 阶段部署。
DEPLOYED

所有工作人员都已使用新代码进行部署（第 1 阶段已完成）。该应用程序支持单表格式，但尚未将其激活。

第 2 阶段的部署从migrateAllEntitiesToLeaseTable设置为true。
PENDING

所有工作人员都运行新代码。KCL 将工作器指标和协调器状态表中的数据迁移到租赁表中。

迁移完成后，默认烘焙时间为 24 小时。
COMPLETE

迁移已完成。KCL 仅使用租用表进行所有读取和写入。不再使用旧的工作器指标和协调器状态表。

终端状态。不会发生进一步的过渡。

有关每种状态、过渡条件和完整状态机行为的详细信息，请参阅 KCL 单表迁移状态机。

注意

“待处理” 和 “完成” 状态之间的默认烘焙时间为 24 小时，但您最多可以将其配置为一周。在此期间，KCL 使用租用表进行所有读取和写入，但不会删除旧表。确认迁移成功后，必须手动删除旧的工作器指标和协调器状态表。KCL 不会自动删除这些表。

回滚注意事项

回滚支持取决于当前：TableMigrationStatus

  • 在第 1 阶段（TableMigrationStatus已设置DEPLOYED或尚未设置）：您可以安全地回滚到以前的版本。新代码在向后兼容模式下运行，并且未向租用表中的非租赁条目写入任何数据。

  • 在第 2 阶段（TableMigrationStatus是DEPLOYED或PENDING）：您可以回滚到第 1 阶段。工作人员恢复使用旧表（多表格式）来表示工作人员指标和协调器状态。迁移已撤消。

  • 完成状态后：不支持回滚。KCL 仅对所有实体使用租赁表。即使代码回滚到第 1 阶段，工作程序仍会继续使用所有实体的租赁表，并且配置将被忽略。

警告

迁移到达 COMPLETE 状态后，应用程序仅在单表模式下运行。migrateAllEntitiesToLeaseTable配置将被忽略，KCL 不会恢复为使用单独的表。确保在移至 COMPLETE 之前的烘焙时间足够长，因为在那之后，即使是代码回滚也不会切换回多个表。

最佳实践

采用单表格式时，请遵循以下最佳实践：

  • 第 1 阶段部署后，验证协调器状态条目是否TableMigration3.5达到DEPLOYED状态。在进入第 2 阶段之前，请确保没有回归。

  • 监视处于TableMigration3.5协调器状态的条目，跟踪已部署、待处理和完成状态的进度。TableMigrationStatus在迁移到达 COMPLETE 之前，状态作为单独的条目存储在协调器状态表中（不存储在租用表中）。

  • 确保在移至 COMPLETE 之前的烘焙时间足够长，因为在那之后，即使是代码回滚也不会切换回多个表。该应用程序仅在单表模式下运行。

  • 迁移完成后，手动删除旧的工作器指标和协调器状态表。KCL 不会自动删除这些表，而只是停止使用它们。

  • 如果您已配置CoordinatorConfig.coordinatorStateTableConfig或LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig，则可以在迁移完成后删除这些配置。在 KCL 3.5 及更高版本中，这些配置已被弃用。