本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

從 KCL 2.x 遷移至 KCL 3.x

本主題提供 step-by-step將取用者從 KCL 2.x 遷移至 3.x KCL 的指示。KCL 3.x 支援 2.x KCL 消費者就地遷移。您可以繼續從 Kinesis 資料串流取用資料，同時以滾動方式遷移工作者。

步驟 1：事前準備

開始使用 KCL 3.x 之前，請確定您具有下列項目：

步驟 2：新增相依性

如果您使用的是 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 Repository KCL上檢查 的最新版本。

步驟 3：設定與遷移相關的組態

若要從 KCL 2.x 遷移至 KCL 3.x，您必須設定下列組態參數：

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 負載平衡演算法給所有執行中的工作者。

步驟 4：遵循 shutdownRequested（） 方法實作的最佳實務

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 先決條件

KCL 3.x 會收集CPU使用率指標，例如從工作者取得CPU使用率，以平衡工作者之間的負載。消費者應用程式工作者可以在 Amazon EC2、Amazon ECS、Amazon EKS或 上執行 AWS Fargate。KCL 3.x 只有在符合下列先決條件時，才能從工作者收集CPU使用率指標：

Amazon Elastic Compute Cloud（Amazon EC2）

Amazon 上的 Amazon Elastic Container Service （Amazon ECS） EC2

Amazon ECS on AWS Fargate

Amazon 上的 Amazon Elastic Kubernetes Service （Amazon EKS） EC2

Amazon EKS on AWS Fargate

步驟 6：更新 3.x KCL 的IAM許可

您必須將下列許可新增至與您的 3.x KCL 取用者應用程式相關聯的IAM角色或政策。這涉及更新KCL應用程式使用的現有IAM政策。如需詳細資訊，請參閱IAM KCL取用者應用程式所需的許可。

步驟 7：將 KCL 3.x 程式碼部署到您的工作者

設定遷移所需的組態並完成所有先前的遷移檢查清單之後，您就可以建置程式碼並將其部署至工作者。

步驟 8：完成遷移

在部署 KCL 3.x 程式碼期間， 會KCL繼續使用來自 2.x KCL 的租用指派演算法。當您成功將 KCL 3.x 程式碼部署到所有工作者時， KCL 會自動偵測此項目，並根據工作者的資源使用率切換到新的租用指派演算法。如需新租用指派演算法的詳細資訊，請參閱 如何將租用KCL指派給工作者並平衡負載。

在部署期間，您可以使用發出至 的下列指標來監控遷移程序 CloudWatch。您可以在 Migration 操作下監控指標。所有指標都是 per-KCL-application指標，並設定為SUMMARY指標層級。如果CurrentState:3xWorker指標的Sum統計資料與您KCL應用程式中的工作者總數相符，則表示遷移至 KCL 3.x 已成功完成。

KCL 在遷移期間提供復原功能至 2.x 相容模式。成功遷移至 KCL 3.x 後，CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X如果不再需要回復，建議您移除 CoordinatorConfig.clientVersionConfig的設定。移除此組態會停止從KCL應用程式發出遷移相關指標。