はじめに
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>
| CurrentLeases | CurrentState | ConsumedReadCapacityUnits | ConsumedWriteCapacityUnits |
|---|---|---|---|
 |
 |
 |
 |
- リースの分配が再び均等になる
-
CurrentState:3xWorkerがCurrentState:2xCompatibleWorkerに戻る - 読み込み量も元の水準に戻る
おわりに
本記事では、KCL 2.x から 3.x への移行時に、リース分配アルゴリズムと DynamoDB の RCU/WCU がどう変化するかを、8 シャード・4 ワーカー構成で検証しました。
本記事の内容はあくまで特定の構成での検証結果であり、すべての環境で同じ挙動になるとは限りませんが、KCL 3.x への移行や検討の際の参考になれば幸いです。