As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Guia de compatibilidade estadual para atualizações do Flink 2.2
Ao atualizar do Flink 1.x para o Flink 2.2, problemas de compatibilidade de estado podem impedir que seu aplicativo seja restaurado a partir de instantâneos. Este guia ajuda você a identificar possíveis problemas de compatibilidade e fornece estratégias de migração.
## Entendendo as mudanças de compatibilidade de estado
O Amazon Managed Service para Apache Flink 2.2 introduz várias alterações de serialização que afetam a compatibilidade de estados. Os seguintes são os principais:
+ **Atualização da versão Kryo**: O Apache Flink 2.2 atualiza o serializador Kryo incluído da versão 2 para a versão 5. Como o Kryo v5 usa um formato de codificação binária diferente do Kryo v2, qualquer estado do operador serializado via Kryo em um ponto de salvamento Flink 1.x não pode ser restaurado no Flink 2.2.
+ **Serialização de coleções Java**: no Flink 1.x, as coleções Java (como `HashMap``ArrayList`, e`HashSet`) POJOs foram serializadas usando o Kryo. O Flink 2.2 introduz serializadores otimizados específicos da coleção que são incompatíveis com o estado serializado Kryo da versão 1.x. Aplicativos que usam coleções Java com serializadores POJO ou Kryo na versão 1.x não podem restaurar esse estado no Flink 2.2. Consulte a [documentação](https://nightlies.apache.org/flink/flink-docs-release-2.2/docs/dev/datastream/fault-tolerance/serialization/types_serialization/) do Flink para obter mais detalhes sobre tipos de dados e serialização.
+ **Compatibilidade do Kinesis Connector**: a versão do conector Kinesis Data Streams (KDS) inferior a 5.0 mantém um estado que não é compatível com o conector Kinesis Flink 2.2 versão 6.0. Você deve migrar para a versão 5.0 ou superior do conector antes da atualização.
## Referência de compatibilidade de serialização
Analise todas as declarações de estado em seu aplicativo e combine os tipos de serialização com a tabela abaixo. Se algum tipo de estado for incompatível, consulte a [Migração estadual](#state-compat-migration) seção antes de continuar com a atualização.
**Referência de compatibilidade de serialização**
| Tipo de serialização | Compatível? | Detalhes |
| --- | --- | --- |
| abril (SpecificRecord,GenericRecord) | Sim | Usa seu próprio formato binário independente do Kryo. Certifique-se de usar as informações do tipo Avro nativo do Flink, não o Avro registrado como um serializador Kryo. |
| Protobuf | Sim | Usa sua própria codificação binária independente do Kryo. Verifique se as alterações do esquema seguem as regras de evolução compatíveis com versões anteriores. |
| POJOs sem coleções | Sim | Gerenciado pelo serializador POJO do Flink — mas somente se a classe atender a todos os critérios do POJO: classe pública, construtor público sem arg, todos os campos públicos ou acessíveis por meio de getters/setters e todos os tipos de campo próprios serializáveis pelo Flink. Um POJO que viole qualquer um desses itens volta silenciosamente para Kryo e se torna incompatível. |
| Personalizado TypeSerializers | Sim | Compatível somente se seu serializador não delegar internamente ao Kryo. |
| Estado da API do SQL e da tabela | Sim (com ressalva) | Usa os serializadores internos do Flink. No entanto, o Apache Flink não garante a compatibilidade de estado entre as versões principais dos aplicativos da API de tabela. Teste primeiro em um ambiente que não seja de produção. |
| POJOs com coleções Java (HashMap,ArrayList,HashSet) | Não | No Flink 1.x, as coleções internas POJOs foram serializadas via Kryo v2. O Flink 2.2 introduz serializadores de coleção dedicados cujo formato binário é incompatível com o formato Kryo v2. |
| Classes de casos Scala | Não | Serializado via Kryo no Flink 1.x. A atualização do Kryo v2 para v5 altera o formato binário. |
| Registros Java | Não | Normalmente, retorne à serialização Kryo no Flink 1.x. Verifique testando comdisableGenericTypes(). |
| Tipos de bibliotecas de terceiros | Não | Os tipos sem um serializador personalizado registrado retornam ao Kryo. A alteração do formato binário Kryo v2 para v5 quebra a compatibilidade. |
| Qualquer tipo usando o Kryo fallback | Não | Se o Flink não conseguir lidar com um tipo com um serializador embutido ou registrado, ele retornará ao Kryo. Todo estado serializado do Kryo a partir de 1.x é incompatível com 2.2. |
## Métodos diagnósticos
Você pode identificar problemas de compatibilidade de estado de forma proativa examinando os registros do aplicativo ou inspecionando os registros após a operação da [UpdateApplication API](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_UpdateApplication.html).
**Identifique o fallback do Kryo em seu aplicativo**
Você pode usar o seguinte padrão de regex em seus registros para identificar o fallback do Kryo em seu aplicativo:
```
Class class (?[^\s]+) cannot be used as a POJO type
```
Log de amostra:
```
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.
```
Se a atualização falhar usando a UpdateApplication API, as exceções a seguir podem indicar que você está enfrentando uma incompatibilidade de estado baseada em serializador:
**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).
```
## Lista de verificação de pré-atualização
+ Revise todas as declarações estaduais em sua inscrição
+ Verifique POJOs com coleções (`HashMap`,`ArrayList`,`HashSet`)
+ Verifique os métodos de serialização para cada tipo de estado
+ Crie um aplicativo de réplica de produção e teste a compatibilidade do estado usando a UpdateApplication API nesta réplica
+ Se o estado for incompatível, selecione uma estratégia em [Migração estadual](#state-compat-migration)
+ Ative a reversão automática na configuração do aplicativo Flink de produção
## Migração estadual
**Reconstruir o estado completo**
Ideal para aplicativos em que o estado pode ser reconstruído a partir dos dados de origem.
Se seu aplicativo puder reconstruir o estado a partir dos dados de origem:
1. Pare o aplicativo Flink 1.x
1. Atualize para o Flink 2.x com código atualizado
1. Comece com `SKIP_RESTORE_FROM_SNAPSHOT`
1. Permitir que o aplicativo reconstrua o estado
```
aws kinesisanalyticsv2 start-application \
--application-name MyApplication \
--run-configuration '{
"ApplicationRestoreConfiguration": {
"ApplicationRestoreType": "SKIP_RESTORE_FROM_SNAPSHOT"
}
}'
```
## Práticas recomendadas
1. **Sempre use Avro ou Protobuf para estados complexos** — eles fornecem a evolução do esquema e são independentes do Kryo
1. **Evite coleções em POJOs** — Use o Flink nativo `ListState` e `MapState` em vez disso
1. **Teste a restauração do estado localmente** — antes da atualização da produção, teste com instantâneos reais
1. **Tire instantâneos com frequência** — especialmente antes das principais atualizações de versões
1. **Ativar reversão automática** — Configure seu aplicativo MSF para reverter automaticamente em caso de falha
1. **Documente seus tipos de estado** — mantenha a documentação de todos os tipos de estados e seus métodos de serialização
1. **Monitore os tamanhos dos pontos de verificação** — O aumento dos tamanhos dos pontos de verificação pode indicar problemas de serialização
## Próximas etapas
**Planeje sua atualização**: Veja[Atualizando para o Flink 2.2: guia completo](flink-2-2-upgrade-guide.md).
Em caso de dúvidas ou problemas durante a migração, consulte [Solucionar problemas do Managed Service for Apache Flink](troubleshooting.md) ou entre em contato com o AWS Support.