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

# 从之前的 KCL 版本迁移
<a name="kcl-migration-previous-versions"></a>

本主题介绍如何从之前 Kinesis Client Library（KCL）版本进行迁移。

## KCL 3.0 中有何新功能？
<a name="kcl-migration-new-3-0"></a>

与之前的版本相比，Kinesis Client Library（KCL）3.0 推出了多项主要改进：
+  通过自动将工作从消费端应用程序队列中过度利用的工作程序重新分配给利用不足的工作程序，从而降低消费端应用程序的计算成本。这种新的负载均衡算法确保在各工作程序之间实现均匀的 CPU 利用率分布，并且无需过度配置工作程序。
+  通过优化租约表中的读取操作，降低了与 KCL 相关的 DynamoDB 成本。
+ 支持当前工作程序完成对已处理记录的检查点操作，从而最大限度地减少租约重新分配给其他工作程序时对数据的再处理。
+  它 Amazon SDK for Java 2.x 用于改进性能和安全功能，完全消除了对 适用于 Java 的 Amazon SDK 1.x 的依赖。

有关更多信息，请参阅 [KCL 3.0 发行说明](https://github.com/awslabs/amazon-kinesis-client/blob/master/CHANGELOG.md)。

**Topics**
+ [KCL 3.0 中有何新功能？](#kcl-migration-new-3-0)
+ [从 KCL 2.x 迁移至 KCL 3.x](kcl-migration-from-2-3.md)
+ [回滚至先前 KCL 版本](kcl-migration-rollback.md)
+ [回滚后前滚到 KCL 3.x](kcl-migration-rollforward.md)
+ [使用预置容量模式的租约表的最佳实践](kcl-migration-lease-table.md)
+ [从 KCL 1.x 迁移到 KCL 3.x](kcl-migration-1-3.md)

# 从 KCL 2.x 迁移至 KCL 3.x
<a name="kcl-migration-from-2-3"></a>

本主题提供了将您的消费者从 KCL 2.x 迁移到 KCL 3.x 的 step-by-step说明。KCL 3.x 支持 KCL 2.x 消费端进行就地迁移。在滚动迁移工作程序时，可继续使用 Kinesis 数据流中的数据。

**重要**  
KCL 3.x 的接口和方法与 KCL 2.x 保持一致。因此，在迁移期间无需更新记录处理代码。但必须设置正确的配置，并检查迁移所需的步骤。我们强烈建议遵循以下迁移步骤，以获得顺畅的迁移体验。

## 步骤 1：先决条件
<a name="kcl-migration-from-2-3-prerequisites"></a>

开始使用 KCL 3.x 之前，请确保已具备以下条件：
+ Java Development Kit（JDK）8 或更高版本
+ 适用于 Java 的 Amazon SDK 2.x
+ 用于依赖项管理的 Maven 或 Gradle

**重要**  
不要在 KCL 3.x 中使用 2.27.19 到 2.27.23 适用于 Java 的 Amazon SDK 版本。这些版本出现的问题会导致使用 KCL 的 DynamoDB 时出现相关异常错误。我们建议您使用 2.28.0 或更高 适用于 Java 的 Amazon SDK 版本来避免此问题。

## 步骤 2：添加依赖项
<a name="kcl-migration-from-2-3-dependencies"></a>

如果您使用的是 Maven，请将以下依赖项添加到您的 `pom.xml` 文件中。确保将 3.x.x 替换为最新的 KCL 版本。

```
<dependency>
    <groupId>software.amazon.kinesis</groupId>
    <artifactId>amazon-kinesis-client</artifactId>
    <version>3.x.x</version> <!-- Use the latest version -->
</dependency>
```

如果使用 Gradle，请在 `build.gradle` 文件中添加以下信息。确保将 3.x.x 替换为最新的 KCL 版本。

```
implementation 'software.amazon.kinesis:amazon-kinesis-client:3.x.x'
```

可以在 [Maven Central 存储库](https://search.maven.org/artifact/software.amazon.kinesis/amazon-kinesis-client)中查看最新版本的 KCL。

## 步骤 3：设置迁移相关配置
<a name="kcl-migration-from-2-3-configuration"></a>

要从 KCL 2.x 迁移至 KCL 3.x，就必须设置以下配置参数：
+ CoordinatorConfig。 clientVersionConfig：此配置决定了应用程序将在哪种 KCL 版本兼容模式下运行。从 KCL 2.x 迁移至 3.x 时，需要将该配置设置为 `CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X`。要设置此配置，请在创建调度器对象时添加以下行：

```
configsBuilder.coordiantorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPLATIBLE_WITH_2X)
```

下面是如何设置 `CoordinatorConfig.clientVersionConfig` 从 KCL 2.x 迁移至 3.x 的示例。您可以按照自己的具体需求，根据需要调整其他配置：

```
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()
);
```

重要的是，由于 KCL 2.x 和 3.x 使用的负载均衡算法不同，消费端应用程序中的所有工作程序在给定时间均使用相同的负载均衡算法。如果使用不同的负载均衡算法运行工作程序，可能会导致负载分配不够理想，因为这两种算法是独立运行的。

借助于这种 KCL 2.x 兼容性设置，KCL 3.x 应用程序可以在兼容 KCL 2.x 的模式下运行，并使用 KCL 2.x 的负载均衡算法，直至消费端应用程序中的所有工作程序都升级到 KCL 3.x。迁移完成后，KCL 会自动切换到完整版 KCL 3.x 功能模式，并开始为所有正在运行的工作程序使用新的 KCL 3.x 负载均衡算法。

**重要**  
如果未使用 `ConfigsBuilder`，而是创建 `LeaseManagementConfig` 对象来设置配置，则必须在 KCL 3.x 或更高版本中再添加一个称为 `applicationName` 的参数。有关详细信息，请参阅[ LeaseManagementConfig 构造函数的编译错误](https://docs.amazonaws.cn/streams/latest/dev/troubleshooting-consumers.html#compiliation-error-leasemanagementconfig)。我们建议使用 `ConfigsBuilder` 来设置 KCL 配置。`ConfigsBuilder` 提供了一种更加灵活、更易于维护的方式来配置 KCL 应用程序。

## 第 4 步：遵循 shutdownRequested() 方法实现的最佳实践
<a name="kcl-migration-from-2-3-best-practice"></a>

KCL 3.x 中推出了一项名为“*优雅移交租约*”的功能，在租约重新分配过程中将租约移交给其他工作程序时，该功能可最大程度减少对数据的再处理。其实现方法是在租约移交之前，对租约表中最后处理的序列号进行检查点操作。为确保优雅移交租约功能的正常运行，必须保证在 `RecordProcessor` 类的 `shutdownRequested` 方法中调用 `checkpointer` 对象。如果在 `shutdownRequested` 方法中未调用 `checkpointer` 对象，可以按照以下示例所示进行实现。

**重要**  
以下实现示例是优雅移交租约的最低要求。需要时可以进行扩展，以添加与检查点相关的其他逻辑。如果当前正在执行任何异步处理，请确保在调用检查点操作之前已对所有传送到下游的记录进行了处理。
虽然优雅移交租约可以显著减小租约转移期间进行数据再处理的可能性，但不能完全消除这种可能性。为保持数据的完整性和一致性，请将下游消费端应用程序设计为具有幂等性。这意味着消费端应用程序应该能够处理潜在的记录重复处理，而不会对整个系统带来不利影响。

```
/**
 * 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);
    } 
}
```

## 步骤 5：检查 KCL 3.x 收集工作程序指标的先决条件
<a name="kcl-migration-from-2-3-worker-metrics"></a>

KCL 3.x 收集 CPU 利用率指标（例如工作程序的 CPU 利用率），以期均匀地平衡各工作程序之间的负载。消费端应用程序的工作程序可运行在 Amazon EC2、Amazon EKS、Amazon EKS 或 Amazon Fargate上。只有在满足以下先决条件时，KCL 3.x 才能从工作程序收集 CPU 利用率指标：

 **Amazon Elastic Compute Cloud（Amazon EC2）**
+ 操作系统必须是 Linux 操作系统。
+ 您必须[IMDSv2](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)在 EC2 实例中启用。

 **Amazon EC2 上的 Amazon Elastic Container Service（Amazon ECS）**
+ 操作系统必须是 Linux 操作系统。
+ 必须启用 [ECS 任务元数据端点版本 4](https://docs.amazonaws.cn/AmazonECS/latest/developerguide/ec2-metadata.html)。
+ Amazon ECS 容器代理版本必须为 1.39.0 或更高版本。

 **Amazon ECS 已开启 Amazon Fargate**
+ 必须启用 [Fargate 任务元数据端点版本 4](https://docs.amazonaws.cn/AmazonECS/latest/developerguide/task-metadata-endpoint-v4-fargate.html)。如果使用的是 Fargate 平台版本 1.4.0 或更高版本，则默认启用此功能。
+ Fargate（平台版本 1.4.0 或更高版本）。

 **Amazon EC2 上的 Amazon Elastic Kubernetes Service（Amazon EKS）** 
+ 操作系统必须是 Linux 操作系统。

 **亚马逊 EKS 开启 Amazon Fargate**
+ Fargate（平台版本 1.3.0 或更高版本）。

**重要**  
如果 KCL 3.x 因为未满足先决条件而无法从工作程序收集 CPU 利用率指标，它将根据每个租约的吞吐量级别重新平衡负载。这种后备再平衡机制可确保所有工作程序都能从分配给各工作程序的租约中获得类似级别的总吞吐量。有关更多信息，请参阅 [KCL 如何向工作程序分配租约并平衡负载](kcl-dynamoDB.md#kcl-assign-leases)。

## 第 6 步：更新 KCL 3.x 的 IAM 权限
<a name="kcl-migration-from-2-3-IAM-permissions"></a>

必须向与 KCL 3.x 消费端应用程序有关的 IAM 角色或策略添加以下权限。这涉及对 KCL 应用程序使用的现有 IAM 策略进行更新。有关更多信息，请参阅 [KCL 消费端应用程序所必需的 IAM 权限](kcl-iam-permissions.md)。

**重要**  
您的现有 KCL 应用程序可能没有在 IAM 策略中添加以下 IAM 操作与资源，因为 KCL 2.x 不需要这些操作与资源。在运行 KCL 3.x 应用程序之前，请确保已添加这些操作与资源：  
动作：`UpdateTable`  
资源 (ARNs): `arn:aws:dynamodb:region:account:table/KCLApplicationName`
动作：`Query`  
资源 (ARNs): `arn:aws:dynamodb:region:account:table/KCLApplicationName/index/*`
操作：`CreateTable`、`DescribeTable`、`Scan`、`GetItem`、`PutItem`、`UpdateItem`、`DeleteItem`  
资源 (ARNs):`arn:aws:dynamodb:region:account:table/KCLApplicationName-WorkerMetricStats`, `arn:aws:dynamodb:region:account:table/KCLApplicationName-CoordinatorState` 
将中的 “区域”、“账户” 和 “KCLApplication名称” 分别替换为您自己的名称 Amazon Web Services 区域、 Amazon Web Services 账户 号码和 KCL 应用程序名称。 ARNs 如果使用配置来自定义 KCL 创建的元数据表的名称，请使用这些指定的表名称而不是 KCL 应用程序名称。

## 第 7 步：将 KCL 3.x 代码部署到工作程序
<a name="kcl-migration-from-2-3-IAM-deploy"></a>

在设置了迁移所需的配置并完成之前所有的迁移清单之后，就可以构建代码并将其部署到工作程序中。

**注意**  
如果您看到构造函数出现编译错误，请参阅`LeaseManagementConfig`构造函数的[编译错误以](https://docs.amazonaws.cn/streams/latest/dev/troubleshooting-consumers.html#compilation-error-leasemanagementconfig)获取疑难解答信息。 LeaseManagementConfig 

## 步骤 8：完成迁移
<a name="kcl-migration-from-2-3-finish"></a>

在部署 KCL 3.x 代码期间，KCL 将继续使用来自 KCL 2.x 的租约分配算法。成功将 KCL 3.x 代码部署到所有工作程序后，KCL 会自动检测部署情况，并根据工作程序的资源利用率切换到新的租约分配算法。有关新租约分配算法的更多详细信息，请参阅[KCL 如何向工作程序分配租约并平衡负载](kcl-dynamoDB.md#kcl-assign-leases)。

在部署期间，您可以使用向其发送以下指标来 CloudWatch监控迁移过程。您可以监控 `Migration` 操作下的指标。所有指标均为 per-KCL-application指标，并设置为`SUMMARY`指标级别。如果 `CurrentState:3xWorker` 指标的 `Sum` 统计数据与 KCL 应用程序的工作程序总数一致，则表示已成功完成向 KCL 3.x 的迁移。

**重要**  
 在所有工作程序做好运行新租约分配算法的准备之后，KCL 至少需要 10 分钟才能切换到新算法。


**CloudWatch KCL 迁移过程的指标**  

| 指标 | 说明 | 
| --- | --- | 
| CurrentState:3xWorker |  成功迁移至 KCL 3.x 并运行新租约分配算法的 KCL 工作程序数量。如果此指标的 `Sum` 计数与工作程序总数一致，则表示已成功完成向 KCL 3.x 的迁移。 [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/streams/latest/dev/kcl-migration-from-2-3.html)  | 
| CurrentState:2xCompatibleWorker |  迁移过程中在 KCL 2.x 兼容模式下运行的 KCL 工作程序数量。该指标若为非零值，表示迁移仍在进行中。 [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/streams/latest/dev/kcl-migration-from-2-3.html)  | 
| Fault |  迁移过程中遇到的异常数量。这些异常大多数是瞬时错误，KCL 3.x 会自动重试以完成迁移。如果发现永久性的 `Fault` 指标值，请查看迁移期间的日志，以进一步排除故障。如果问题仍然存在，请联系 Amazon Web Services 支持。 [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/streams/latest/dev/kcl-migration-from-2-3.html)  | 
| GsiStatusReady |  租约表上创建全局二级索引（GSI）的状态。该指标表示租约表上的 GSI 是否已创建，这是运行 KCL 3.x 的一个先决条件。其值为 0 或 1，其中 1 表示创建成功。在回滚状态下，不会发出该指标。再次向前滚动后，可以继续监控该指标。 [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/streams/latest/dev/kcl-migration-from-2-3.html)  | 
| workerMetricsReady |  所有工作程序指标的发送状态。该指标表示是否所有工作程序都发出诸如 CPU 利用率之类的指标。其值为 0 或 1，其中 1 表示所有工作程序均已成功发出指标，并准备好使用新的租约分配算法。在回滚状态下，不会发出该指标。再次向前滚动后，可以继续监控该指标。 [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/streams/latest/dev/kcl-migration-from-2-3.html)  | 

KCL 在迁移期间提供回滚至 2.x 兼容模式的能力。成功迁移至 KCL 3.x 后，如果不再需要回滚，我们建议移除 `CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X` 的 `CoordinatorConfig.clientVersionConfig` 设置。移除该配置之后，就不会从 KCL 应用程序发出与迁移相关的指标。

**注意**  
我们建议在迁移期间和完成迁移后，监控应用程序的性能和稳定性一段时间。如果发现任何问题，可使用 [KCL 迁移工具](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py)回滚工作程序以使用 KCL 2.x 兼容功能。

# 回滚至先前 KCL 版本
<a name="kcl-migration-rollback"></a>

本主题介绍将消费端回滚到先前版本的步骤。需要回滚时，可执行一个两步流程：

1. 运行 [KCL Migration Tool](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py)。

1. 重新部署以前的 KCL 版本代码（可选）。

## 步骤 1：运行 KCL 迁移工具
<a name="kcl-migration-rollback-tool"></a>

当需要回滚到先前 KCL 版本时，必须运行 KCL 迁移工具。KCL 迁移工具可完成两项重要任务：
+ 它在 DynamoDB 中的租约表上移除一个名为工作线程指标表的元数据表和全局二级索引。这两个构件由 KCL 3.x 创建，但在回滚到先前版本时并不需要。
+ 它使所有工作程序在与 KCL 2.x 兼容的模式下运行，并开始使用先前 KCL 版本中使用的负载平衡算法。如果 KCL 3.x 中的新负载均衡算法存在问题，这将立即缓解问题。

**重要**  
DynamoDB 中的协调器状态表必须存在，并且在迁移、回滚和前滚过程中不得删除。

**注意**  
重要的是，使用者应用程序中的所有工作线程在给定时间均使用相同的负载均衡算法。KCL 迁移工具可确保 KCL 3.x 使用者应用程序中的所有工作线程都切换到 KCL 2.x 兼容模式，以便在部署回滚到先前 KCL 版本期间，所有工作线程都运行相同的负载均衡算法。

您可以在 [KCL 存储库的脚本目录中下载 [KCL GitHub](https://github.com/awslabs/amazon-kinesis-client/tree/master) 迁移工具](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py)。可以从任何工作程序或具备以下必需权限的主机上运该脚本：写入协调器状态表、删除工作程序指标表以及更新租约表的权限。可参考 [KCL 消费端应用程序所必需的 IAM 权限](kcl-iam-permissions.md) 获取运行脚本所需的 IAM 权限。每个 KCL 应用程序只能运行该脚本一次。您可使用以下命令运行 KCL 迁移工具：

```
python3 ./KclMigrationTool.py --region <region> --mode rollback [--application_name <applicationName>] [--lease_table_name <leaseTableName>] [--coordinator_state_table_name <coordinatorStateTableName>] [--worker_metrics_table_name <workerMetricsTableName>]
```

**参数**
+ --region：`<region>`替换为你的。 Amazon Web Services 区域
+ --application\$1name：如果您为 DynamoDB 元数据表（租约表、协调器状态表和工作线程指标表）使用默认名称，则需要此参数。如果您为这些表指定了自定义名称，则可以忽略此参数。将 `<applicationName>` 替换为实际的 KCL 应用程序名称。如果未提供自定义名称，该工具将使用此名称来派生默认表名称。
+ --lease\$1table\$1name（可选）：如果您在 KCL 配置中为租约表设置了自定义名称，则需要此参数。如果您使用的是默认表名称，则可以忽略此参数。将 `leaseTableName` 替换为您为租约表指定的自定义表名称。
+ --coordinator\$1state\$1table\$1name（可选）：如果您在 KCL 配置中为协调器状态表设置了自定义名称，则需要此参数。如果您使用的是默认表名称，则可以忽略此参数。将 `<coordinatorStateTableName>` 替换为您为协调器状态表指定的自定义表名称。
+ --worker\$1metrics\$1table\$1name（可选）：如果您在 KCL 配置中为工作线程指标表设置了自定义名称，则需要此参数。如果您使用的是默认表名称，则可以忽略此参数。将 `<workerMetricsTableName>` 替换为您为工作线程指标表指定的自定义表名称。

## 步骤 2：使用先前 KCL 版本重新部署代码（可选）
<a name="kcl-migration-rollback-redeploy"></a>

 运行 KCL 迁移工具来进行回滚后，您将看到以下消息之一：
+ **消息 1：**“回滚已完成。您的 KCL 应用程序正在运行 KCL 2.x 兼容模式。如果您看不到回归缓解，请使用先前 KCL 版本部署代码，回滚到先前的应用程序二进制文件。”
  + **必需的操作：**这意味着您的工作人员正在 KCL 2.x 兼容模式下运行。如果仍有问题，请使用先前 KCL 版本将代码重新部署到工作程序。
+ **消息 2：**“回滚已完成。您的 KCL 应用程序正在运行 KCL 3.x 功能模式。您无需回滚到以前的应用程序二进制文件，除非在 5 分钟内看不到任何缓解该问题的措施。如果仍有问题，请使用先前 KCL 版本部署代码，以回滚到先前的应用程序二进制文件。”
  + **必需的操作：**这意味着您的工作人员在 KCL 3.x 模式下运行，KCL 迁移工具已将所有工作人员切换到兼容 KCL 2.x 的模式。如果问题得到解决，则无需使用之前的 KCL 版本重新部署代码。如果仍有问题，请使用先前 KCL 版本将代码重新部署到工作程序。

 

# 回滚后前滚到 KCL 3.x
<a name="kcl-migration-rollforward"></a>

本主题介绍在回滚后将消费端前滚到 KCL 3.x 的步骤。当您需要前滚时，必须完成一个由两步组成的过程：

1. 运行 [KCL Migration Tool](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py)。

1. 使用 KCL 3.x 部署代码。

## 步骤 1：运行 KCL 迁移工具
<a name="kcl-migration-rollback-tool"></a>

运行 KCL Migration Tool。具有以下命令的 KCL 迁移工具，用于前滚到 KCL 3.x：

```
python3 ./KclMigrationTool.py --region <region> --mode rollforward [--application_name <applicationName>] [--coordinator_state_table_name <coordinatorStateTableName>]
```

**参数**
+ --region：`<region>`替换为你的。 Amazon Web Services 区域
+ --application\$1name：如果您为协调器状态表使用默认名称，则需要此参数。如果您已为协调器状态表指定了自定义名称，则可以忽略此参数。将 `<applicationName>` 替换为实际的 KCL 应用程序名称。如果未提供自定义名称，该工具将使用此名称来派生默认表名称。
+ --coordinator\$1state\$1table\$1name（可选）：如果您在 KCL 配置中为协调器状态表设置了自定义名称，则需要此参数。如果您使用的是默认表名称，则可以忽略此参数。将 `<coordinatorStateTableName>` 替换为您为协调器状态表指定的自定义表名称。

在前滚模式下运行迁移工具后，KCL 会创建 KCL 3.x 所需的以下 DynamoDB 资源：
+ 租约表上的全局二级索引
+ 工作线程指标表

## 步骤 2：使用 KCL 3.x 部署代码
<a name="kcl-migration-rollback-redeploy"></a>

运行 KCL 迁移工具以进行前滚后，使用 KCL 3.x 将代码部署到工作线程。按照 [步骤 8：完成迁移](kcl-migration-from-2-3.md#kcl-migration-from-2-3-finish) 完成迁移。

# 使用预置容量模式的租约表的最佳实践
<a name="kcl-migration-lease-table"></a>

如果 KCL 应用程序的租约表已切换至预置容量模式，KCL 3.x 会在采用预置计费模式的租约表上创建全局二级索引，租约表的读取容量单位（RCU）和写入容量单位（WCU）与基础租约表一致。创建全局二级索引时，我们建议在 DynamoDB 控制台中监控全局二级索引的实际使用情况，并根据需要调整容量单位。有关切换由 KCL 创建的 DynamoDB 元数据表容量模式的更详细指南，请参阅[KCL 创建的元数据表的 DynamoDB 容量模式](kcl-dynamoDB.md#kcl-capacity-mode)。

**注意**  
默认情况下，KCL 使用按需容量模式在租约表上创建元数据表，例如租约表、工作程序指标表和协调器状态表以及全局二级索引。我们建议您使用按需容量模式，以便根据您的使用量变化自动调整容量。

# 从 KCL 1.x 迁移到 KCL 3.x
<a name="kcl-migration-1-3"></a>

本主题说明如何将消费端从 KCL 1.x 迁移至 KCL 3.x。与 KCL 2.x 和 KCL 3.x 相比，KCL 1.x 使用不同的类和接口。必须先将记录处理器、记录处理器工厂和工作线程类迁移到 KCL 2.x/3.x 兼容格式，然后按照将 KCL 2.x 迁移到 KCL 3.x 的迁移步骤进行操作。可直接从 KCL 1.x 升级至 KCL 3.x。
+ **步骤 1：迁移记录处理器**

  按照[将消费端从 KCL 1.x 迁移至 KCL 2.x](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#recrod-processor-migration) 页面中的[迁移记录处理器](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#recrod-processor-migration)部分进行操作。
+ **步骤 2：迁移记录处理器工厂**

  按照[将消费端从 KCL 1.x 迁移至 KCL 2.x](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#recrod-processor-migration) 页面中的[迁移记录处理器工厂](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#recrod-processor-factory-migration)部分进行操作。
+ **步骤 3：迁移工作人员**

  按照[将消费端从 KCL 1.x 迁移至 KCL 2.x](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#recrod-processor-migration) 页面中的[迁移工作程序](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#worker-migration)部分进行操作。
+ **第 4 步：迁移 KCL 1.x 配置**

  按照[将消费端从 KCL 1.x 迁移至KCL 2.x](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#recrod-processor-migration) 页面中的[配置 Amazon Kinesis 客户端](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#client-configuration)部分进行操作。
+ **第 5 步：检查闲置时间删除和客户端配置移除情况**

  按照[将消费端从 KCL 1.x 迁移至 KCL 2.x](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#recrod-processor-migration) 页面中的[闲置时间删除](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#idle-time-removal)和[客户端配置移除](https://docs.amazonaws.cn/streams/latest/dev/kcl-migration.html#client-configuration-removals)部分进行操作。
+ **第 6 步：按照 KCL 2.x 到 KCL 3.x 迁移 step-by-step指南中的说明进行操作**

  遵循 [从 KCL 2.x 迁移至 KCL 3.x](kcl-migration-from-2-3.md) 页面上的说明完成迁移。如需回滚到之前 KCL 版本，或在回滚后向前滚到 KCL 3.x，请参阅[回滚至先前 KCL 版本](kcl-migration-rollback.md)和[回滚后前滚到 KCL 3.x](kcl-migration-rollforward.md)。

**重要**  
不要在 KCL 3.x 中使用 2.27.19 到 2.27.23 适用于 Java 的 Amazon SDK 版本。这些版本出现的问题会导致使用 KCL 的 DynamoDB 时出现相关异常错误。我们建议您使用 2.28.0 或更高 适用于 Java 的 Amazon SDK 版本来避免此问题。