KCL 3.5.x 以降の単一テーブル形式への移行
KCL 3.5 以降では、単一テーブル形式を使用して、すべての DynamoDB メタデータを単一のリーステーブルに統合できます。デフォルトでは、KCL 3.x はアプリケーションごとにリーステーブル、ワーカーメトリクステーブル、コーディネーター状態テーブルの 3 つの DynamoDB テーブルを作成します。単一テーブル形式では、これら 3 つのテーブルが 1 つに減るため、DynamoDB のアカウントレベルのテーブル制限を回避できます。
単一テーブル形式の仕組み
単一テーブル形式では、KCL はワーカーメトリクスとコーディネーター状態エントリをリースエントリとともにリーステーブルに保存します。各項目には、異なるレコードタイプを区別する entityType 属性が含まれています。
ワーカーメトリクスとコーディネーター状態項目は、リーステーブルと同じプライマリキー構造を使用しますが、個別の entityType 値が含まれます。この属性により、KCL はテーブルスキャン中に各項目の目的を識別できます。
KCL の各コンポーネントは、entityType 属性に基づいてビジネスロジックに必要なエントリをフィルタリングして抽出します。例えば、リース割り当てマネージャー (LAM) はリースとワーカーのメトリクスエントリをフィルタリングしてリース割り当てを実行します。
単一テーブル形式を設定する
単一テーブル形式を有効にする方法は、現在の KCL バージョンによって異なります。
-
KCL 2.x を使用している場合: 更新された移行ガイドに従って KCL 3.5 にアップグレードします。2.x から 3.5 への新しい移行には、デフォルトで単一テーブル形式が使用されます。
-
KCL 3.0～3.4 を使用している場合: 単一テーブル形式に移行するには、2 フェーズのデプロイを実行する必要があります。以下の設定と移行の手順を参照してください。
既存の KCL 3.x のお客様の場合は、CoordinatorConfig で migrateAllEntitiesToLeaseTable 設定オプションを設定します。このオプションは、KCL がすべてのメタデータエンティティタイプをリーステーブルに保存するかどうかを制御します。
| 値 | デフォルト | 効果 |
|---|---|---|
false |
はい |
KCL は、ワーカーメトリクスとコーディネーター状態に対して個別のテーブルを使用します。アプリケーションコードは単一テーブル形式をサポートしていますが、アクティブ化していません。 |
true |
いいえ |
KCL は、ワーカーメトリクスとコーディネーター状態データのリーステーブルへの書き込みを開始します。 |
KCL 3.x から単一テーブル形式に移行するには、2 フェーズのデプロイが必要です。
-
フェーズ 1:
migrateAllEntitiesToLeaseTableをfalse(デフォルト) に設定して、更新された KCL 3.5 コードをデプロイします。これにより、単一テーブル形式をサポートする新しいコードがインストールされますが、移行はアクティブ化されません。 -
フェーズ 2: すべてのワーカーが新しいコードを実行し、
TableMigrationStatusがDEPLOYEDに達し、リグレッションがないことを確認したら、migrateAllEntitiesToLeaseTableをtrueに設定して再度デプロイし、移行を開始します。
移行ステータス
TableMigrationStateMachine は、複数テーブル形式から単一テーブル形式への移行を管理します。KCL は、コーディネーター状態テーブルの TableMigration3.5 という個別のコーディネーター状態エントリで、現在の移行状態を追跡します。状態、遷移、説明の完全なリストについては、GitHub ウェブサイトの KCL 単一テーブルの移行状態
| 状態 | 説明 | 移行条件 |
|---|---|---|
INIT |
初期状態。すべてのワーカーは、ワーカーメトリクス統計の最小限のサポートコードを出力しています。ワーカーは引き続きワーカーメトリクスをレガシーテーブルに出力し、ワーカーメトリクスとコーディネーター状態をレガシーテーブルとリーステーブルの両方から読み取ります。機能的には、INIT と DEPLOYED に違いはありません。 |
すべてのワーカーは、ベイク時間の間、最小限のサポートコードを着実に出力します。アプリケーションはフェーズ 2 のデプロイに移行する準備ができています。 |
DEPLOYED |
すべてのワーカーに新しいコードがデプロイされました (フェーズ 1 が完了)。アプリケーションは単一テーブル形式をサポートしていますが、アクティブ化されていません。 |
|
PENDING |
すべてのワーカーが新しいコードを実行します。KCL は、ワーカーメトリクスとコーディネーター状態テーブルからリーステーブルにデータを移行します。 |
移行が完了すると、24 時間のデフォルトのベイク時間が経過します。 |
COMPLETE |
移行が完了しました。KCL は、すべての読み取りと書き込みにリーステーブルだけを使用します。以前のワーカーメトリクスとコーディネーター状態テーブルは、使用されなくなりました。 |
終了状態。これ以上の移行は行われません。 |
各状態、移行条件、および完全なステートマシンの動作の詳細については、GitHub ウェブサイトの KCL 単一テーブル移行ステートマシン
注記
PENDING 状態と COMPLETE 状態の間のデフォルトのベイク時間は 24 時間ですが、最大 1 週間まで設定できます。この期間中、KCL はすべての読み取りと書き込みにリーステーブルを使用しますが、古いテーブルは削除しません。移行が成功したことを確認したら、古いワーカーメトリクスとコーディネーター状態テーブルを手動で削除する必要があります。KCL はこれらのテーブルを自動的に削除しません。
移行メトリクス
KCL を使用すると、CloudWatch メトリクスを使用して単一テーブルの移行の進行状況と正常性をモニタリングできます。これらのメトリクスを使用して、ワーカーが新しいコードを採用していることを確認し、移行の状態を追跡します。移行中に DynamoDB の読み取り、書き込み、または削除の障害を検出することもできます。次の表は、メトリクスを出力する KCL オペレーション (メトリクスディメンション) と、各メトリクスが出力されるタイミングによってメトリクスをグループ化しています。
選出されたリーダーワーカーは、移行が進行中かどうかにかかわらず、次のメトリクスを継続的に出力します。
Operation |
メトリクス |
単位 |
説明 |
|---|---|---|---|
|
|
なし |
現在の DynamoDB 移行ステータスの序数: |
|
|
なし |
フリート内のすべてのリース所有ワーカーの最小限のサポートコード。 |
選択されたリーダーワーカーは、移行の進行中にのみ、次のメトリクスを出力します。
Operation |
メトリクス |
単位 |
説明 |
|---|---|---|---|
|
|
カウント |
単一の DynamoDB テーブルでの運用をサポートしているが、単一テーブルの使用にまだ移行していないワーカーの数。 |
|
|
カウント |
単一テーブルへの書き込みに移行したワーカーの数。これらのワーカーは、テーブルの移行が完了するまで、複数のテーブルから読み取りを行う可能性があります。 |
|
|
カウント |
単一の DynamoDB テーブルでの運用をサポートしていない 3.5 より前のバージョンのワーカーの数。 |
|
|
カウント |
DynamoDB への書き込み失敗時は |
|
|
カウント |
DynamoDB での削除の失敗時は |
|
|
カウント |
|
|
|
カウント |
CoordinatorState エントリのトランザクション移動が成功した場合は |
|
|
ミリ秒 |
非同期移動オペレーションの所要時間。 |
|
|
カウント |
正常に移動されたバッチの数。 |
すべてのワーカーは、移行の進行中に次のメトリクスを出力します。
Operation |
メトリクス |
単位 |
説明 |
|---|---|---|---|
|
|
カウント |
DynamoDB から |
|
|
ミリ秒 |
ステートマシンの実行期間。 |
|
|
カウント |
正常に初期化された場合は |
|
|
ミリ秒 |
初期化オペレーションの所要時間。 |
これらのメトリクスを使用して、移行をいつ進めるかを決定します。StatusOrdinal が一貫して 2 (DEPLOYED) で、PrePhase1Worker が 0 の場合、すべてのワーカーが単一テーブル形式をサポートしていることになり、テーブル移行デプロイのフェーズ 2 に移行できます。StatusOrdinal が 4 (COMPLETE) に達したら、レガシーテーブルを安全に削除できます。
ロールバックに関する考慮事項
ロールバックのサポートは、現在の TableMigrationStatus によって異なります。
-
フェーズ 1 中 (
TableMigrationStatusがDEPLOYEDまたは未設定): 以前のバージョンに安全にロールバックできます。新しいコードは下位互換性モードで実行され、リーステーブルのリース以外のエントリにデータが書き込まれていません。 -
フェーズ 2 中 (
TableMigrationStatusがDEPLOYEDまたはPENDING): フェーズ 1 にロールバックできます。ワーカーは、ワーカーメトリクスとコーディネーター状態のレガシーテーブル (複数テーブル形式) の使用に戻ります。移行は元に戻されます。 -
COMPLETE 状態後: ロールバックはサポートされていません。KCL は、すべてのエンティティに対してリーステーブルのみを使用します。コードがフェーズ 1 にロールバックされても、ワーカーはすべてのエンティティに対してリーステーブルを使用し続け、設定は無視されます。
警告
移行が COMPLETE 状態になると、アプリケーションは単一テーブルモードでのみ動作します。migrateAllEntitiesToLeaseTable 設定は無視され、KCL は個別のテーブルの使用には戻りません。COMPLETE に移行する前にベイク時間が十分であることを確認してください。COMPLETE に達した後は、コードをロールバックしても複数テーブル設定には戻らないためです。
ベストプラクティス
単一テーブル形式を採用する場合は、次のベストプラクティスに従ってください。
-
フェーズ 1 のデプロイ後、コーディネーター状態エントリ
TableMigration3.5がDEPLOYEDステータスに達していることを確認します。フェーズ 2 に進む前に、リグレッションがないことを確認してください。 -
TableMigration3.5コーディネーター状態エントリのTableMigrationStatusをモニタリングして、DEPLOYED、PENDING、COMPLETE の各ステータスの進行状況を追跡します。移行が COMPLETE に達するまで、ステータスは (リーステーブルではなく) コーディネーター状態テーブルに個別のエントリとして保存されます。 -
COMPLETE に移行する前にベイク時間が十分であることを確認してください。COMPLETE に達した後は、コードをロールバックしても複数テーブル設定には戻らないためです。アプリケーションは単一テーブルモードでのみ機能します。
-
移行が COMPLETE に達したら、古いワーカーメトリクスとコーディネーター状態テーブルを手動で削除します。KCL はこれらのテーブルを自動的に削除せず、使用を停止するだけです。
-
CoordinatorConfig.coordinatorStateTableConfigまたはLeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfigを設定している場合は、移行の完了後にこれらの設定を削除できます。これらの設定は KCL 3.5 以降では廃止されています。
