# KCL 3.5.x\+의 단일 테이블 형식으로 마이그레이션
KCL 3.5부터는 **단일 테이블 형식**을 사용하여 모든 DynamoDB 메타데이터를 단일 리스 테이블로 통합할 수 있습니다. 기본적으로 KCL 3.x는 각 애플리케이션에 대해 리스 테이블, 워커 지표 테이블, 코디네이터 상태 테이블이라는 세 개의 DynamoDB 테이블을 생성합니다. 단일 테이블 형식은 이 세 테이블을 하나로 줄여 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이 모든 메타데이터 엔터티 유형을 리스 테이블에 저장할지 여부를 제어합니다.
**`migrateAllEntitiesToLeaseTable` 구성 값**
| 값 | 기본값 | Effect |
| --- | --- | --- |
| false | 예 | KCL이 워커 지표와 코디네이터 상태에 대해 별도의 테이블을 사용합니다. 애플리케이션 코드는 단일 테이블 형식을 지원하지만 활성화하지는 않습니다. |
| true | 아니요 | KCL이 워커 지표 및 코디네이터 상태 데이터를 리스 테이블에 쓰기 시작합니다. `TableMigrationStatus`가 `DEPLOYED`에 도달하고 회귀가 없는지 확인하기 위한 베이크 기간을 거친 후 2단계 배포에서 이 값을 설정합니다. |
KCL 3.x에서 단일 테이블 형식으로 마이그레이션하려면 2단계 배포가 필요합니다.
1. **1단계:** `migrateAllEntitiesToLeaseTable`이 `false`(기본값)로 설정된 업데이트된 KCL 3.5 코드를 배포합니다. 그러면 단일 테이블 형식을 지원하지만 마이그레이션을 활성화하지 않는 새 코드가 설치됩니다.
1. **2단계:** 모든 워커가 새 코드를 실행하고 `TableMigrationStatus`가 `DEPLOYED`에 도달하고 회귀가 없는지 확인한 후 `migrateAllEntitiesToLeaseTable`을 `true`로 설정한 상태로 다시 배포하여 마이그레이션을 시작합니다.
## 마이그레이션 상태
`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)를 참조하세요.
**단일 테이블 형식 마이그레이션 상태**
| State | 설명 | 전환 조건 |
| --- | --- | --- |
| INIT | 원래 상태. 모든 워커가 워커 지표 통계에서 최소 지원 코드를 내보내고 있습니다. 워커는 계속해서 워커 지표를 레거시 테이블로 내보내고 레거시 테이블과 리스 테이블 모두에서 워커 지표 및 코디네이터 상태를 읽습니다. 기능적으로 INIT와 DEPLOYED 간에는 차이가 없습니다. | 모든 워커는 베이크 소요 시간 동안 최소 지원 코드를 안정적으로 내보냅니다. 애플리케이션이 2단계 배포로 이동할 준비가 되었습니다. |
| DEPLOYED | 모든 워커가 새 코드로 배포되었습니다(1단계 완료). 애플리케이션은 단일 테이블 형식을 지원하지만 활성화하지는 않았습니다. | 2단계 배포는 `migrateAllEntitiesToLeaseTable`이 `true`로 설정된 상태로 시작됩니다. |
| 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은 이러한 테이블을 자동으로 삭제하지 않습니다.
## 마이그레이션 지표
KCL을 사용하면 CloudWatch 지표를 사용하여 단일 테이블 마이그레이션의 진행 상황 및 상태를 모니터링할 수 있습니다. 이러한 지표를 사용하여 워커가 새 코드를 채택했는지 확인하고 마이그레이션이 거친 상태를 추적합니다. 마이그레이션 중에 DynamoDB 읽기, 쓰기 또는 삭제 오류를 감지할 수도 있습니다. 다음 표에서는 지표를 내보내는 KCL 작업(지표 차원) 및 각 지표가 내보내지는 시점을 기준으로 지표가 그룹화되어 있습니다.
선정된 리더 워커는 마이그레이션이 진행 중인지 여부에 관계없이 다음 지표를 지속적으로 내보냅니다.
**리더가 항상 내보내는 지표**
| 연산 | 지표 | 단위 | 설명 |
| --- | --- | --- | --- |
| `TableMigration` | `StatusOrdinal` | 없음 | 현재 DynamoDB 마이그레이션 상태의 서수: `0` = UNKNOWN, `1` = INIT, `2` = DEPLOYED, `3` = PENDING, `4` = COMPLETE. |
| `WorkerMetrics` | `FleetMinSupportCode` | 없음 | 플릿의 모든 리스 소유 워커에 대한 최소 지원 코드입니다. |
선정된 리더 워커는 마이그레이션이 진행되는 동안에만 다음 지표를 내보냅니다.
**마이그레이션 중에 리더가 내보내는 지표**
| 연산 | 지표 | 단위 | 설명 |
| --- | --- | --- | --- |
| `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` | 개수 | 성공적으로 이동한 배치 수입니다. |
마이그레이션이 진행되는 동안 모든 워커가 다음 지표를 내보냅니다.
**마이그레이션 중에 모든 워커가 내보내는 지표**
| 연산 | 지표 | 단위 | 설명 |
| --- | --- | --- | --- |
| `TableMigration` | `ReadFault` | 개수 | DynamoDB로부터 `TableMigrationState` 읽기 실패 시 `1`, 성공 시 `0`입니다. |
| `TableMigration` | `Time` | 밀리초 | 상태 시스템 실행 시간입니다. |
| `TableMigrationInitialize` | `Success` | 개수 | 초기화 성공 시 `1`, 실패 시 `0`입니다. |
| `TableMigrationInitialize` | `Time` | 밀리초 | 초기화 작업의 지속 시간입니다. |
이러한 지표를 사용하여 마이그레이션을 진행할 시기를 결정합니다. `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로 이동하기 전에 베이크 소요 시간이 충분한지 확인하세요. 그 이후에는 코드 롤백도 다중 테이블로 다시 전환되지 않기 때문입니다.
## 모범 사례
단일 테이블 형식을 채택할 때는 다음 모범 사례를 따르세요.
+ 1단계 배포 후 코디네이터 상태 항목 `TableMigration3.5`가 `DEPLOYED` 상태에 도달하는지 확인합니다. 2단계로 진행하기 전에 회귀가 없는지 확인합니다.
+ `TableMigration3.5` 코디네이터 상태 항목의 `TableMigrationStatus`를 모니터링하여 DEPLOYED, PENDING 및 COMPLETE 상태의 진행 상황을 추적합니다. 마이그레이션이 COMPLETE에 도달할 때까지 상태가 코디네이터 상태 테이블에 별도의 항목(리스 테이블에는 없음)으로 저장됩니다.
+ COMPLETE로 이동하기 전에 베이크 소요 시간이 충분한지 확인하세요. 그 이후에는 코드 롤백도 다중 테이블로 다시 전환되지 않기 때문입니다. 애플리케이션은 단일 테이블 모드에서만 작동합니다.
+ 마이그레이션이 COMPLETE에 도달하면 이전 워커 지표 및 코디네이터 상태 테이블을 수동으로 삭제합니다. KCL은 이러한 테이블을 자동으로 삭제하지 않으며 사용만 중지합니다.
+ `CoordinatorConfig.coordinatorStateTableConfig` 또는 `LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig`를 구성한 경우 마이그레이션이 완료된 후 이러한 구성을 제거할 수 있습니다. 이러한 구성은 KCL 3.5 이상에서 더 이상 사용되지 않습니다.