기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Flink 2.2 업그레이드를 위한 상태 호환성 가이드
<a name="state-compatibility"></a>

Flink 1.x에서 Flink 2.2로 업그레이드할 때 상태 호환성 문제로 인해 애플리케이션이 스냅샷에서 복원되지 않을 수 있습니다. 이 가이드는 잠재적 호환성 문제를 식별하고 마이그레이션 전략을 제공하는 데 도움이 됩니다.

## 상태 호환성 변경 사항 이해
<a name="state-compat-understanding"></a>

Amazon Managed Service for Apache Flink 2.2에는 상태 호환성에 영향을 미치는 여러 직렬화 변경 사항이 도입되었습니다. 다음은 주요 항목입니다.
+ **Kryo 버전 업그레이드**: Apache Flink 2.2는 번들링된 Kryo 직렬 변환기를 버전 2에서 버전 5로 업그레이드합니다. Kryo v5는 Kryo v2와 다른 이진 인코딩 형식을 사용하므로 Flink 1.x 저장점에서 Kryo를 통해 직렬화된 연산자 상태는 Flink 2.2에서 복원할 수 없습니다.
+ **Java 컬렉션 직렬화**: Flink 1.x에서 POJOs 내의 Java 컬렉션(예: `HashMap``ArrayList`, 및 `HashSet`)은 Kryo를 사용하여 직렬화되었습니다. Flink 2.2에는 1.x의 Kryo 직렬화 상태와 호환되지 않는 컬렉션별 최적화 직렬 변환기가 도입되었습니다. 1.x에서 POJO 또는 Kryo 직렬 변환기와 함께 Java 컬렉션을 사용하는 애플리케이션은 Flink 2.2에서이 상태를 복원할 수 없습니다. 데이터 유형 및 직렬화에 대한 자세한 내용은 Flink [설명서를](https://nightlies.apache.org/flink/flink-docs-release-2.2/docs/dev/datastream/fault-tolerance/serialization/types_serialization/) 참조하세요.
+ **Kinesis 커넥터 호환성**: 5.0 미만의 Kinesis Data Streams(KDS) 커넥터 버전은 Flink 2.2 Kinesis 커넥터 버전 6.0과 호환되지 않는 상태를 유지합니다. 업그레이드하기 전에 커넥터 버전 5.0 이상으로 마이그레이션해야 합니다.

## 직렬화 호환성 참조
<a name="state-compat-reference"></a>

애플리케이션의 모든 상태 선언을 검토하고 직렬화 유형을 아래 표와 일치시킵니다. 상태 유형이 호환되지 않는 경우 업그레이드를 진행하기 전에 [상태 마이그레이션](#state-compat-migration) 섹션을 참조하세요.


**직렬화 호환성 참조**  

| 직렬화 유형 | 호환되나요? | 세부 정보 | 
| --- | --- | --- | 
| Avro(SpecificRecord, GenericRecord) | 예 | Kryo와 독립적인 자체 바이너리 형식을 사용합니다. Kryo 직렬 변환기로 등록된 Avro가 아닌 Flink의 기본 Avro 유형 정보를 사용하고 있는지 확인합니다. | 
| Protobuf | 예 | Kryo와 독립적인 자체 바이너리 인코딩을 사용합니다. 스키마 변경 사항이 이전 버전과 호환되는 진화 규칙을 따르는지 확인합니다. | 
| 컬렉션POJOs  | 예 | Flink의 POJO 직렬 변환기에서 처리 - 클래스가 퍼블릭 클래스, 퍼블릭 no-arg 생성자, 모든 퍼블릭 필드 또는 getter/setters를 통해 액세스할 수 있는 필드, Flink에서 직렬화할 수 있는 모든 필드 유형 자체 등 모든 POJO 기준을 충족하는 경우에만 처리됩니다. 이러한 문제를 위반하는 POJO는 자동으로 Kryo로 돌아가 호환되지 않습니다. | 
| 사용자 지정 TypeSerializers | 예 | serializer가 Kryo에 내부적으로 위임하지 않는 경우에만 호환됩니다. | 
| SQL 및 테이블 API 상태 | 예(주의 사항 포함) | Flink의 내부 직렬 변환기를 사용합니다. 그러나 Apache Flink는 Table API 애플리케이션의 메이저 버전 간 상태 호환성을 보장하지 않습니다. 비프로덕션 환경에서 테스트합니다. | 
| Java 컬렉션POJOs(HashMap, ArrayList, HashSet) | 아니요 | Flink 1.x에서는 POJOs 내의 컬렉션이 Kryo v2를 통해 직렬화되었습니다. Flink 2.2에는 바이너리 형식이 Kryo v2 형식과 호환되지 않는 전용 컬렉션 직렬화기가 도입되었습니다. | 
| Scala 사례 클래스 | 아니요 | Flink 1.x의 Kryo를 통해 직렬화됩니다. Kryo v2에서 v5로 업그레이드하면 바이너리 형식이 변경됩니다. | 
| Java 레코드 | 아니요 | 일반적으로 Flink 1.x에서 Kryo 직렬화로 돌아갑니다. 를 사용하여 테스트하여 확인합니다disableGenericTypes(). | 
| 타사 라이브러리 유형 | 아니요 | 등록된 사용자 지정 직렬 변환기가 없는 유형은 Kryo로 돌아갑니다. Kryo v2에서 v5로의 바이너리 형식 변경은 호환성을 깨뜨립니다. | 
| Kryo 대체를 사용하는 모든 유형 | 아니요 | Flink가 내장 또는 등록된 직렬 변환기가 있는 유형을 처리할 수 없는 경우 Kryo로 돌아갑니다. 1.x의 모든 Kryo 직렬화 상태는 2.2와 호환되지 않습니다. | 

## 진단 방법
<a name="state-compat-diagnostics"></a>

애플리케이션 로그를 보거나 [UpdateApplication API](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_UpdateApplication.html) 작업 후 로그를 검사하여 상태 호환성 문제를 사전에 식별할 수 있습니다.

**애플리케이션에서 Kryo 대체 식별**

로그에서 다음 정규식 패턴을 사용하여 애플리케이션에서 Kryo 대체를 식별할 수 있습니다.

```
Class class (?<className>[^\s]+) cannot be used as a POJO type
```

샘플 로그:

```
Class class org.apache.flink.streaming.connectors.kinesis.model.SequenceNumber
cannot be used as a POJO type because not all fields are valid POJO fields,
and must be processed as GenericType. Please read the Flink documentation on
"Data Types & Serialization" for details of the effect on performance and
schema evolution.
```

UpdateApplication API를 사용하여 업그레이드에 실패하면 다음 예외에 따라 serializer 기반 상태 비호환성이 발생할 수 있습니다.

**IndexOutOfBoundsException**

```
Caused by: java.lang.IndexOutOfBoundsException: Index 116 out of bounds for length 1
    at java.base/jdk.internal.util.Preconditions.outOfBounds(Unknown Source)
    at java.base/jdk.internal.util.Preconditions.outOfBoundsCheckIndex(Unknown Source)
    at java.base/jdk.internal.util.Preconditions.checkIndex(Unknown Source)
    at java.base/java.util.Objects.checkIndex(Unknown Source)
    at java.base/java.util.ArrayList.get(Unknown Source)
    at com.esotericsoftware.kryo.util.MapReferenceResolver.getReadObject(MapReferenceResolver.java:77)
    at com.esotericsoftware.kryo.Kryo.readReferenceOrNull(Kryo.java:923)
    ... 23 more
```

**StateMigrationException(POJOSerializer)**

```
Caused by: org.apache.flink.util.StateMigrationException: The new state serializer
(org.apache.flink.api.java.typeutils.runtime.PojoSerializer@8bf85b5d) must not be
incompatible with the old state serializer
(org.apache.flink.api.java.typeutils.runtime.PojoSerializer@3282ee3).
```

## 업그레이드 전 체크리스트
<a name="state-compat-checklist"></a>
+ 애플리케이션의 모든 상태 선언 검토
+ 컬렉션POJOs 확인(`HashMap`, `ArrayList`, `HashSet`)
+ 각 상태 유형에 대한 직렬화 메서드 확인
+ 이 복제본에서 UpdateApplication API를 사용하여 Prod 복제본 애플리케이션 생성 및 상태 호환성 테스트
+ 상태가 호환되지 않는 경우에서 전략을 선택합니다. [상태 마이그레이션](#state-compat-migration) 
+ 프로덕션 Flink 애플리케이션 구성에서 자동 롤백 활성화

## 상태 마이그레이션
<a name="state-compat-migration"></a>

**재구축 완료 상태**

소스 데이터에서 상태를 다시 빌드할 수 있는 애플리케이션에 가장 적합합니다.

애플리케이션이 소스 데이터에서 상태를 다시 빌드할 수 있는 경우:

1. Flink 1.x 애플리케이션 중지

1. 업데이트된 코드를 사용하여 Flink 2.x로 업그레이드

1. 로 시작 `SKIP_RESTORE_FROM_SNAPSHOT`

1. 애플리케이션이 상태를 다시 빌드하도록 허용

```
aws kinesisanalyticsv2 start-application \
    --application-name MyApplication \
    --run-configuration '{
        "ApplicationRestoreConfiguration": {
            "ApplicationRestoreType": "SKIP_RESTORE_FROM_SNAPSHOT"
        }
    }'
```

## 모범 사례
<a name="state-compat-best-practices"></a>

1. **복잡한 상태에는 항상 Avro 또는 Protobuf 사용** - 스키마 진화를 제공하고 Kryo에 독립적입니다.

1. **POJOs에서 컬렉션 방지** - 대신 Flink의 네이티브 사용 `ListState` `MapState` 

1. **로컬에서 상태 복원 테스트** - 프로덕션 업그레이드 전에 실제 스냅샷으로 테스트

1. **자주 스냅샷 생성 **- 특히 메이저 버전 업그레이드 전

1. **자동 롤백 활성화 -** 실패 시 자동으로 롤백하도록 MSF 애플리케이션을 구성합니다.

1. **상태 유형 문서화** - 모든 상태 유형 및 직렬화 방법에 대한 문서 유지 관리

1. **체크포인트 크기 모니터링** - 체크포인트 크기가 증가하면 직렬화 문제가 발생할 수 있습니다.

## 다음 단계
<a name="state-compat-next-steps"></a>

**업그레이드 계획: 섹션을 참조하세요**[Flink 2.2로 업그레이드: 전체 가이드](flink-2-2-upgrade-guide.md).

마이그레이션 중 질문이나 문제는 섹션을 참조[Managed Service for Apache Flink 문제 해결](troubleshooting.md)하거나 AWS Support에 문의하세요.