はじめに

Amazon Kinesis Client Library (KCL) は、Kinesis Data Streams からデータを読み取るコンシューマーアプリケーションを構築するためのライブラリです。
2024年にリリースされたKCL 3.xでは、リースの分配アルゴリズムが大幅に変更されました。

バージョン	分配アルゴリズム
2.xまで	均等にリースを分配
3.x以降	負荷状況に応じてリースを分配（CPU使用率などを考慮）

本記事では、KCL 2.xから3.xへのアップグレード時にどのようにリースの分配が変化するのかを、実際の検証結果をもとに紹介します。

アップグレード時のワーカー動作検証

検証構成

下図のように「8シャード・4ワーカー」の構成を用意し、検証しました。

※ KCLのバージョンは 3.1.3 を使用

検証シナリオ

KCL2.xと3.xのコンテナイメージをそれぞれ用意し、ワーカーの入れ替えを行いながら、以下6つのフェーズで、各メトリクスの変化を観測しました。

ワーカーのコンテナイメージを 2.x -> 2.xに入れ替えた場合（アップグレード前）
ワーカーの半分を 2.x -> 3.xに入れ替えた場合（カナリアリリース）
ワーカー全台を3.xに入れ替えた場合（全台リリース）
全台リリース後、一定時間経過した場合
全台リリース完了後、3.x -> 3.xの入れ替えを実施した場合（アップグレード完了後）
ロールバックコマンドを実施してアルゴリズムを2.xに戻した場合

各フェーズで確認したメトリクスは以下の通りです。

メトリクス名	説明
CurrentLeases	1ワーカーが、リース更新処理の後に所有しているシャードリースの数。実質的に「そのワーカーが今いくつのシャードを担当しているか」を示すメトリクス。
CurrentState:2xCompatibleWorker	KCL 2.x から 3.x への移行中に、2.x 互換モード（`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X`）で動作している KCL ワーカーの数を表すメトリクス。 Sum が 0 でない場合は、まだ移行が完了しておらず、一部ワーカーが 2.x 互換モードのまま残っていることを示す。
CurrentState:3xWorker	KCL 3.x への移行後、新しい負荷分散アルゴリズムで動作している KCLワーカーの数を表すメトリクス。 Sum がワーカー総数と一致していれば、KCL 2.x から 3.x への移行が完了していることを示す。
ConsumedReadCapacityUnits	DynamoDB テーブル（KCL のリーステーブルなど）が、ある期間に消費した読み取りキャパシティユニット（RCU）の合計。
ConsumedWriteCapacityUnits	DynamoDB テーブル（KCL のリーステーブルなど）が、ある期間に消費した書き込みキャパシティユニット（WCU）の合計。

リースの分配状況を確認するために CurrentLeases を確認し、移行状況を確認するために CurrentState:2xCompatibleWorker / CurrentState:3xWorker を確認するようにしました。

また、KCL3.xではリーステーブルの読み込みが改善されていることが明記されています。

https://github.com/awslabs/amazon-kinesis-client/releases/tag/v3.0.0
Optimized DynamoDB RCU usage
KCL 3.x optimizes DynamoDB read capacity unit (RCU) usage on the lease table by implementing a global secondary index with leaseOwner as the partition key. This index mirrors the leaseKey attribute from the base lease table, allowing workers to efficiently discover their assigned leases by querying the index instead of scanning the entire table.

そのため、リーステーブルの ConsumedReadCapacityUnits にどの程度の変化があるか、また書き込み量に変化がないかを確認するために ConsumedWriteCapacityUnits も合わせて観測しました。

観測結果

フェーズ1: ワーカーのコンテナイメージを 2.x -> 2.xに入れ替えた場合（アップグレード前）

CurrentLeases	CurrentState	ConsumedReadCapacityUnits	ConsumedWriteCapacityUnits

リースは各ワーカーに均等に分配されている
移行はまだ開始されていないため、CurrentStateのグラフはなし
読み込み・書き込み量は一定

フェーズ2: ワーカーの半分を 2.x -> 3.xに入れ替えた場合（カナリアリリース）

KCL 2.x から KCL 3.x に移行する際に必要な設定値 CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X を有効にしています。

2.xのアルゴリズムと3.xのアルゴリズムを混在させることはできないため、移行時には必須の設定となります。

CurrentLeases	CurrentState	ConsumedReadCapacityUnits	ConsumedWriteCapacityUnits

リース分配アルゴリズムは まだ2.xのまま
2.xと3.xのワーカーが混在していても、互換性の設定によって2.xアルゴリズムが維持される

フェーズ3: ワーカー全台を3.xに入れ替えた場合（全台リリース）

CurrentLeases	CurrentState	ConsumedReadCapacityUnits	ConsumedWriteCapacityUnits

この時点でもリース分配アルゴリズムは 2.xのまま
すべてのワーカーが3.xになっても、アルゴリズムは即座には切り替わらない

フェーズ4: 全台リリース後、一定時間経過した場合

CurrentLeases	CurrentState	ConsumedReadCapacityUnits	ConsumedWriteCapacityUnits

リース分配アルゴリズムが自動的に3.xに切り替わる
切り替え直後、一部のワーカーでリース数が0になる場合がある
- ヘルスチェックなどでリース数を監視している場合失敗しうるため、ヘルスチェックの条件・実装を見直した方が良い
読み込み量が削減される（テーブルスキャンからインデックス参照に変わるため、今回は約2割程度の削減）
書き込み量はあまり変わらない

フェーズ5: 全台リリース完了後、3.x -> 3.xの入れ替えを実施した場合（アップグレード完了後）

CurrentLeases	CurrentState	ConsumedReadCapacityUnits	ConsumedWriteCapacityUnits

入れ替え前後とも、リース分配が3.xのアルゴリズムで実施されている
読み込み・書き込み量は変化なし

フェーズ6: ロールバックコマンドを実施してアルゴリズムを2.xに戻した場合

ロールバックはコンテナイメージを戻すのではなく、まずKCL移行ツールによりロールバックコマンドを実行する必要があります。
これによって分配アルゴリズムが2.xに戻ります。
Amazon Kinesis Streams > デベロッパーガイド > 以前のバージョンにロールバックする

コマンド例

cd amazon-kinesis-client/scripts/

# 仮想環境にboto3インストール
% python3 -m venv .venv
% source .venv/bin/activate
(.venv) % python3 -m pip install boto3

# ロールバックの実行
(.venv) % python3 ./KclMigrationTool.py --region <REGION> --mode rollback --application_name <APPLICATION_NAME>