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á.

Migrar da KCL 2.x para a KCL 3.x

Este tópico fornece step-by-step instruções para migrar seu consumidor do KCL 2.x para o KCL 3.x. A KCL 3.x oferece suporte à migração local de consumidores da KCL 2.x. Você pode continuar consumindo os dados do seu fluxo de dados do Kinesis enquanto migra seus operadores de forma contínua.

Etapa 1: pré-requisitos

Antes de começar a usar a KCL 3.x, certifique-se de ter os pré-requisitos apresentados a seguir:

Etapa 2: adicionar dependências

Se estiver usando Maven, adicione a dependência a seguir ao seu arquivo pom.xml. Certifique-se de ter substituído 3.x.x pela versão mais recente da KCL.

<dependency>
    <groupId>software.amazon.kinesis</groupId>
    <artifactId>amazon-kinesis-client</artifactId>
    <version>3.x.x</version> <!-- Use the latest version -->
</dependency>

Se você estiver usando Gradle, adicione o seguinte ao seu arquivo build.gradle. Certifique-se de ter substituído 3.x.x pela versão mais recente da KCL.

implementation 'software.amazon.kinesis:amazon-kinesis-client:3.x.x'

A versão mais recente da KCL pode ser obtida no Repositório central do Maven.

Etapa 3: definir a configuração relacionada à migração

Para migrar da KCL 2.x para a KCL 3.x, é necessário definir o seguinte parâmetro de configuração:

configsBuilder.coordiantorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPLATIBLE_WITH_2X)

Veja a seguir um exemplo de como configurar CoordinatorConfig.clientVersionConfig para migrar da KCL 2.x para a 3.x. Você pode ajustar outras configurações conforme necessário, com base em seus requisitos específicos:

Scheduler scheduler = new Scheduler(
    configsBuilder.checkpointConfig(),
    configsBuilder.coordiantorConfig().clientVersionConfig(ClientVersionConfig.CLIENT_VERSION_CONFIG_COMPLATIBLE_WITH_2X),
    configsBuilder.leaseManagementConfig(),
    configsBuilder.lifecycleConfig(),
    configsBuilder.metricsConfig(),
    configsBuilder.processorConfig(),
    configsBuilder.retrievalConfig()
);

É importante que todos os operadores em sua aplicação de consumo usem o mesmo algoritmo de balanceamento de carga em um determinado momento, uma vez que a KCL 2.x e a 3.x usam algoritmos diferentes para balancear a carga. A execução de operadores com diferentes algoritmos de balanceamento de carga pode causar uma distribuição de carga abaixo do ideal, pois os dois algoritmos operam de forma independente.

Essa configuração de compatibilidade da KCL 2.x permite que sua aplicação da KCL 3.x seja executada em um modo compatível com a KCL 2.x e use o algoritmo de balanceamento de carga para a KCL 2.x até que todos os operadores da sua aplicação de consumo tenham sido atualizados para a KCL 3.x. Quando a migração for concluída, a KCL mudará automaticamente para o modo de funcionalidade completa da KCL 3.x e começará a usar o novo algoritmo de balanceamento de carga da KCL 3.x para todos os operadores em execução.

Etapa 4: siga as melhores práticas para a implementação do método shutdownRequested()

A KCL 3.x introduz um atributo chamado transferência normal de concessões para minimizar o reprocessamento de dados quando uma concessão é transferida para outro operador como parte do processo de reatribuição da concessão. Isso é obtido mediante verificação do último número de sequência processado na tabela de concessões antes da transferência da concessão. Para garantir que a transferência normal da concessão funcione corretamente, o objeto checkpointer tem de ser invocado dentro do método shutdownRequested em sua classe RecordProcessor. Se você invocar o objeto checkpointer dentro do método shutdownRequested, poderá implementá-lo conforme ilustrado no exemplo a seguir.

/**
 * Invoked when either Scheduler has been requested to gracefully shutdown
 * or lease ownership is being transferred gracefully so the current owner
 * gets one last chance to checkpoint.
 *
 * Checkpoints and logs the data a final time.
 *
 * @param shutdownRequestedInput Provides access to a checkpointer, allowing a record processor to checkpoint
 *                               before the shutdown is completed.
 */
public void shutdownRequested(ShutdownRequestedInput shutdownRequestedInput) {
    try {
       // Ensure that all delivered records are processed 
       // and has been successfully flushed to the downstream before calling 
       // checkpoint
       // If you are performing any asynchronous processing or flushing to
       // downstream, you must wait for its completion before invoking
       // the below checkpoint method.
        log.info("Scheduler is shutting down, checkpointing.");
        shutdownRequestedInput.checkpointer().checkpoint();
    } catch (ShutdownException | InvalidStateException e) {
        log.error("Exception while checkpointing at requested shutdown. Giving up.", e);
    } 
}

Etapa 5: verifique os pré-requisitos da KCL 3.x para coletar métricas de operadores

A KCL 3.x coleta métricas de utilização da CPU, como a utilização da CPU pelos operadores, para equilibrar uniformemente a carga entre os operadores. Os operadores de aplicativos para consumidores podem trabalhar na Amazon EC2, Amazon ECS, Amazon EKS ouAWS Fargate. A KCL 3.x pode coletar métricas de utilização da CPU dos operadores somente quando os seguintes pré-requisitos forem atendidos:

Amazon Elastic Compute Cloud(Amazon EC2)

Amazon Elastic Container Service (Amazon ECS) na Amazon EC2

Amazon ECS em AWS Fargate

Amazon Elastic Kubernetes Service (Amazon EKS) na Amazon EC2

Amazon EKS em AWS Fargate

Etapa 6: atualizar as permissões do IAM para a KCL 3.x

É necessário adicionar as permissões a seguir para o perfil do IAM ou a política associada à aplicação de consumo da KCL 3.x. Isso inclui a atualização da política do IAM atual, usada pela aplicação da KCL. Para obter mais informações, consulte Permissões do IAM necessárias para aplicativos de consumo da KCL.

Etapa 7: implantar o código da KCL 3.x em seus operadores

Depois de definir a configuração necessária para a migração e concluir todas as listas de verificação de migração anteriores, você pode criar e implantar seu código para seus operadores.

Etapa 8: concluir a migração

Durante a implantação do código da KCL 3.x, a KCL continua usando o algoritmo de atribuição de concessões da KCL 2.x. Após a implantação do código da KCL 3.x em todos os seus operadores, a KCL detectará isso automaticamente e passará a adotar o novo algoritmo de atribuição de concessões com base na utilização de recursos pelos operadores. Para obter mais detalhes sobre o novo algoritmo de atribuição de concessões, consulte Como a KCL atribui concessões aos operadores e equilibra a carga.

Durante a implantação, você pode monitorar o processo de migração com as seguintes métricas emitidas para o. CloudWatch É possível monitorar métricas na operação de Migration. Todas as métricas são per-KCL-application métricas e são definidas para o nível SUMMARY métrico. Se a estatística Sum da métrica CurrentState:3xWorker corresponder ao número total de operadores em sua aplicação da KCL, a migração para KCL 3.x foi concluída com êxito.

O KCL fornece capacidade de reversão para o modo compatível com 2.x durante a migração. Depois que a migração para a KCL 3.x for concluída, recomendamos que você remova a configuração CoordinatorConfig.clientVersionConfig de CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X se a reversão não for mais necessária. A remoção dessa configuração interrompe a emissão de métricas relacionadas à migração da aplicação da KCL.