# KCL 3.5.x 以降の単一テーブル形式への移行
<a name="kcl-single-table-format"></a>

KCL 3.5 以降では、**単一テーブル形式**を使用して、すべての DynamoDB メタデータを単一のリーステーブルに統合できます。デフォルトでは、KCL 3.x はアプリケーションごとにリーステーブル、ワーカーメトリクステーブル、コーディネーター状態テーブルの 3 つの DynamoDB テーブルを作成します。単一テーブル形式では、これら 3 つのテーブルが 1 つに減るため、DynamoDB のアカウントレベルのテーブル制限を回避できます。

## 単一テーブル形式の仕組み
<a name="kcl-single-table-how-it-works"></a>

単一テーブル形式では、KCL はワーカーメトリクスとコーディネーター状態エントリをリースエントリとともにリーステーブルに保存します。各項目には、異なるレコードタイプを区別する `entityType` 属性が含まれています。

ワーカーメトリクスとコーディネーター状態項目は、リーステーブルと同じプライマリキー構造を使用しますが、個別の `entityType` 値が含まれます。この属性により、KCL はテーブルスキャン中に各項目の目的を識別できます。

KCL の各コンポーネントは、`entityType` 属性に基づいてビジネスロジックに必要なエントリをフィルタリングして抽出します。例えば、リース割り当てマネージャー (LAM) はリースとワーカーのメトリクスエントリをフィルタリングしてリース割り当てを実行します。

## 単一テーブル形式を設定する
<a name="kcl-single-table-config"></a>

単一テーブル形式を有効にする方法は、現在の KCL バージョンによって異なります。
+ **KCL 2.x を使用している場合:** 更新された移行ガイドに従って KCL 3.5 にアップグレードします。2.x から 3.5 への新しい移行には、デフォルトで単一テーブル形式が使用されます。
+ **KCL 3.0～3.4 を使用している場合:** 単一テーブル形式に移行するには、2 フェーズのデプロイを実行する必要があります。以下の設定と移行の手順を参照してください。

既存の KCL 3.x のお客様の場合は、`CoordinatorConfig` で `migrateAllEntitiesToLeaseTable` 設定オプションを設定します。このオプションは、KCL がすべてのメタデータエンティティタイプをリーステーブルに保存するかどうかを制御します。


**`migrateAllEntitiesToLeaseTable` の設定値**  

| 値 | デフォルト | 効果 | 
| --- | --- | --- | 
| false | はい | KCL は、ワーカーメトリクスとコーディネーター状態に対して個別のテーブルを使用します。アプリケーションコードは単一テーブル形式をサポートしていますが、アクティブ化していません。 | 
| true | いいえ | KCL は、ワーカーメトリクスとコーディネーター状態データのリーステーブルへの書き込みを開始します。`TableMigrationStatus` が `DEPLOYED` に達し、リグレッションがないことをベイク期間で確認した後、フェーズ 2 のデプロイでこの値を設定します。 | 

KCL 3.x から単一テーブル形式に移行するには、2 フェーズのデプロイが必要です。

1. **フェーズ 1:** `migrateAllEntitiesToLeaseTable` を `false` (デフォルト) に設定して、更新された KCL 3.5 コードをデプロイします。これにより、単一テーブル形式をサポートする新しいコードがインストールされますが、移行はアクティブ化されません。

1. **フェーズ 2:** すべてのワーカーが新しいコードを実行し、`TableMigrationStatus` が `DEPLOYED` に達し、リグレッションがないことを確認したら、`migrateAllEntitiesToLeaseTable` を `true` に設定して再度デプロイし、移行を開始します。

## 移行ステータス
<a name="kcl-single-table-states"></a>

`TableMigrationStateMachine` は、複数テーブル形式から単一テーブル形式への移行を管理します。KCL は、コーディネーター状態テーブルの `TableMigration3.5` という個別のコーディネーター状態エントリで、現在の移行状態を追跡します。状態、遷移、説明の完全なリストについては、GitHub ウェブサイトの [KCL 単一テーブルの移行状態](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java)を参照してください。


**単一テーブル形式の移行状態**  

| 状態 | 説明 | 移行条件 | 
| --- | --- | --- | 
| INIT | 初期状態。すべてのワーカーは、ワーカーメトリクス統計の最小限のサポートコードを出力しています。ワーカーは引き続きワーカーメトリクスをレガシーテーブルに出力し、ワーカーメトリクスとコーディネーター状態をレガシーテーブルとリーステーブルの両方から読み取ります。機能的には、INIT と DEPLOYED に違いはありません。 | すべてのワーカーは、ベイク時間の間、最小限のサポートコードを着実に出力します。アプリケーションはフェーズ 2 のデプロイに移行する準備ができています。 | 
| DEPLOYED | すべてのワーカーに新しいコードがデプロイされました (フェーズ 1 が完了)。アプリケーションは単一テーブル形式をサポートしていますが、アクティブ化されていません。 | `migrateAllEntitiesToLeaseTable` を `true` に設定して、フェーズ 2 のデプロイを開始します。 | 
| PENDING | すべてのワーカーが新しいコードを実行します。KCL は、ワーカーメトリクスとコーディネーター状態テーブルからリーステーブルにデータを移行します。 | 移行が完了すると、24 時間のデフォルトのベイク時間が経過します。 | 
| COMPLETE | 移行が完了しました。KCL は、すべての読み取りと書き込みにリーステーブルだけを使用します。以前のワーカーメトリクスとコーディネーター状態テーブルは、使用されなくなりました。 | 終了状態。これ以上の移行は行われません。 | 

各状態、移行条件、および完全なステートマシンの動作の詳細については、GitHub ウェブサイトの [KCL 単一テーブル移行ステートマシン](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java)についてのページを参照してください。

**注記**  
PENDING 状態と COMPLETE 状態の間のデフォルトのベイク時間は 24 時間ですが、最大 1 週間まで設定できます。この期間中、KCL はすべての読み取りと書き込みにリーステーブルを使用しますが、古いテーブルは削除しません。移行が成功したことを確認したら、古いワーカーメトリクスとコーディネーター状態テーブルを手動で削除する必要があります。KCL はこれらのテーブルを自動的に削除しません。

## 移行メトリクス
<a name="kcl-single-table-metrics"></a>

KCL を使用すると、CloudWatch メトリクスを使用して単一テーブルの移行の進行状況と正常性をモニタリングできます。これらのメトリクスを使用して、ワーカーが新しいコードを採用していることを確認し、移行の状態を追跡します。移行中に DynamoDB の読み取り、書き込み、または削除の障害を検出することもできます。次の表は、メトリクスを出力する KCL オペレーション (メトリクスディメンション) と、各メトリクスが出力されるタイミングによってメトリクスをグループ化しています。

選出されたリーダーワーカーは、移行が進行中かどうかにかかわらず、次のメトリクスを継続的に出力します。


**リーダーが常に発行するメトリクス**  

| Operation | メトリクス | 単位 | 説明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `StatusOrdinal` | なし | 現在の DynamoDB 移行ステータスの序数: `0` = UNKNOWN、`1` = INIT、`2` = DEPLOYED、`3` = PENDING、`4` = COMPLETE。 | 
| `WorkerMetrics` | `FleetMinSupportCode` | なし | フリート内のすべてのリース所有ワーカーの最小限のサポートコード。 | 

選択されたリーダーワーカーは、移行の進行中にのみ、次のメトリクスを出力します。


**移行中にリーダーが発行するメトリクス**  

| Operation | メトリクス | 単位 | 説明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `Phase1Worker` | カウント | 単一の DynamoDB テーブルでの運用をサポートしているが、単一テーブルの使用にまだ移行していないワーカーの数。 | 
| `TableMigration` | `Phase2Worker` | カウント | 単一テーブルへの書き込みに移行したワーカーの数。これらのワーカーは、テーブルの移行が完了するまで、複数のテーブルから読み取りを行う可能性があります。 | 
| `TableMigration` | `PrePhase1Worker` | カウント | 単一の DynamoDB テーブルでの運用をサポートしていない 3.5 より前のバージョンのワーカーの数。 | 
| `TableMigration` | `WriteFault` | カウント | DynamoDB への書き込み失敗時は `1`、成功時は `0`。 | 
| `TableMigration` | `DeleteFault` | カウント | DynamoDB での削除の失敗時は `1`、成功時は `0`。 | 
| `TableMigration` | `CompletionFault` | カウント | `COMPLETE` ステータスのトランザクション書き込みが失敗した場合は `1`、成功した場合は `0`。 | 
| `TableMigrationAsyncMove` | `Success` | カウント | CoordinatorState エントリのトランザクション移動が成功した場合は `1`、失敗した場合は `0`。 | 
| `TableMigrationAsyncMove` | `Time` | ミリ秒 | 非同期移動オペレーションの所要時間。 | 
| `TableMigrationAsyncMove` | `BatchCount` | カウント | 正常に移動されたバッチの数。 | 

すべてのワーカーは、移行の進行中に次のメトリクスを出力します。


**移行中にすべてのワーカーによって出力されるメトリクス**  

| Operation | メトリクス | 単位 | 説明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `ReadFault` | カウント | DynamoDB から `TableMigrationState` の読み取りに失敗した場合は `1`、成功した場合は `0`。 | 
| `TableMigration` | `Time` | ミリ秒 | ステートマシンの実行期間。 | 
| `TableMigrationInitialize` | `Success` | カウント | 正常に初期化された場合は `1`、失敗した場合は `0`。 | 
| `TableMigrationInitialize` | `Time` | ミリ秒 | 初期化オペレーションの所要時間。 | 

これらのメトリクスを使用して、移行をいつ進めるかを決定します。`StatusOrdinal` が一貫して `2` (DEPLOYED) で、`PrePhase1Worker` が `0` の場合、すべてのワーカーが単一テーブル形式をサポートしていることになり、テーブル移行デプロイのフェーズ 2 に移行できます。`StatusOrdinal` が `4` (COMPLETE) に達したら、レガシーテーブルを安全に削除できます。

## ロールバックに関する考慮事項
<a name="kcl-single-table-rollback"></a>

ロールバックのサポートは、現在の `TableMigrationStatus` によって異なります。
+ **フェーズ 1 中** (`TableMigrationStatus` が `DEPLOYED` または未設定): 以前のバージョンに安全にロールバックできます。新しいコードは下位互換性モードで実行され、リーステーブルのリース以外のエントリにデータが書き込まれていません。
+ **フェーズ 2 中** (`TableMigrationStatus` が `DEPLOYED` または `PENDING`): フェーズ 1 にロールバックできます。ワーカーは、ワーカーメトリクスとコーディネーター状態のレガシーテーブル (複数テーブル形式) の使用に戻ります。移行は元に戻されます。
+ **COMPLETE 状態後**: ロールバックはサポートされていません。KCL は、すべてのエンティティに対してリーステーブルのみを使用します。コードがフェーズ 1 にロールバックされても、ワーカーはすべてのエンティティに対してリーステーブルを使用し続け、設定は無視されます。

**警告**  
移行が COMPLETE 状態になると、アプリケーションは単一テーブルモードでのみ動作します。`migrateAllEntitiesToLeaseTable` 設定は無視され、KCL は個別のテーブルの使用には戻りません。COMPLETE に移行する前にベイク時間が十分であることを確認してください。COMPLETE に達した後は、コードをロールバックしても複数テーブル設定には戻らないためです。

## ベストプラクティス
<a name="kcl-single-table-best-practices"></a>

単一テーブル形式を採用する場合は、次のベストプラクティスに従ってください。
+ フェーズ 1 のデプロイ後、コーディネーター状態エントリ `TableMigration3.5` が `DEPLOYED` ステータスに達していることを確認します。フェーズ 2 に進む前に、リグレッションがないことを確認してください。
+ `TableMigration3.5` コーディネーター状態エントリの `TableMigrationStatus` をモニタリングして、DEPLOYED、PENDING、COMPLETE の各ステータスの進行状況を追跡します。移行が COMPLETE に達するまで、ステータスは (リーステーブルではなく) コーディネーター状態テーブルに個別のエントリとして保存されます。
+ COMPLETE に移行する前にベイク時間が十分であることを確認してください。COMPLETE に達した後は、コードをロールバックしても複数テーブル設定には戻らないためです。アプリケーションは単一テーブルモードでのみ機能します。
+ 移行が COMPLETE に達したら、古いワーカーメトリクスとコーディネーター状態テーブルを手動で削除します。KCL はこれらのテーブルを自動的に削除せず、使用を停止するだけです。
+ `CoordinatorConfig.coordinatorStateTableConfig` または `LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig` を設定している場合は、移行の完了後にこれらの設定を削除できます。これらの設定は KCL 3.5 以降では廃止されています。