Como funciona o formato de tabela única Configurar o formato de tabela única Estados de migração Métricas de migração Considerações sobre reversão Práticas recomendadas

Migração para o formato de tabela única para KCL 3.5.x+

A partir da KCL 3.5, você pode consolidar todos os metadados do DynamoDB em uma única tabela de concessão usando o formato de tabela única. Por padrão, a KCL 3.x cria três tabelas do DynamoDB para cada aplicação: a tabela de concessão, a tabela de métricas de operador e a tabela de estado de coordenador. O formato de tabela única reduz essas três tabelas para uma, o que ajuda a evitar os limites de tabelas no nível da conta do DynamoDB.

Como funciona o formato de tabela única

No formato de tabela única, a KCL armazena as métricas de operador e as entradas de estado do coordenador na tabela de concessão junto com as entradas de concessão. Cada item inclui um atributo entityType que distingue os diferentes tipos de registro.

As métricas de operador e os itens de estado do coordenador usam a mesma estrutura de chave primária da tabela de concessão, mas incluem um valor entityType diferente. Esse atributo permite que a KCL identifique a finalidade de cada item durante as verificações de tabela.

Cada componente da KCL filtra as entradas necessárias para a lógica de negócios com base no atributo entityType. Por exemplo, o Lease Assignment Manager (LAM) filtra as entradas de concessão e de métricas de operador para realizar a atribuição de concessão.

Configurar o formato de tabela única

A forma como você habilita o formato de tabela única depende da sua versão atual da KCL:

Se você estiver usando a KCL 2.x: siga o guia de migração atualizado para atualizar para a KCL 3.5. O formato de tabela única é usado por padrão para novas migrações da versão 2.x para a 3.5.
Se você estiver usando a KCL 3.0–3.4: execute uma implantação em duas fases para migrar para o formato de tabela única. Confira as etapas de configuração e migração a seguir.

Para clientes existentes da KCL 3.x, defina a opção de configuração migrateAllEntitiesToLeaseTable em CoordinatorConfig. Essa opção controla se a KCL armazena todos os tipos de entidade de metadados na tabela de concessão.

Valores de configuração para `migrateAllEntitiesToLeaseTable`
Valor	Padrão	Efeito
`false`	Sim	A KCL usa tabelas separadas para métricas de operador e estado do coordenador. O código do aplicativo oferece suporte ao formato de tabela única, mas não o ativa.
`true`	Não	A KCL começa a gravar as métricas de operador e os dados do estado do coordenador na tabela de concessão. Defina esse valor na implantação da Fase 2 depois que `TableMigrationStatus` atingir `DEPLOYED` e você tiver verificado que não há regressões.

A migração da KCL 3.x para o formato de tabela única requer uma implantação em duas fases:

Fase 1: implante o código KCL 3.5 atualizado com migrateAllEntitiesToLeaseTable definido como false (o padrão). Isso instala o novo código que oferece suporte ao formato de tabela única, mas não ativa a migração.
Fase 2: depois que todos os operadores executarem o novo código e o TableMigrationStatus atingir DEPLOYED, e você tiver verificado que não há regressões, implante novamente com migrateAllEntitiesToLeaseTable definido como true para iniciar a migração.

Estados de migração

A TableMigrationStateMachine gerencia a transição do formato de várias tabelas para o formato de tabela única. A KCL rastreia o estado atual da migração em uma entrada separada do estado do coordenador chamada TableMigration3.5 na tabela de estado do coordenador. Para ver a lista completa de estados, transições e descrições, consulte Estados de migração de tabela única da KCL no site do GitHub.

Estados de migração em formato de tabela única
Estado	Descrição	Condição de transição
`INIT`	Estado inicial. Todos os operadores estão emitindo o código mínimo de suporte nas estatísticas de métricas de operador. Os operadores continuam emitindo métricas de operador na tabela legada e lendo as métricas de operador e o estado do coordenador nas tabelas legada e de concessão. Funcionalmente, não há diferença entre INIT e DEPLOYED.	Todos os operadores emitem o código mínimo de suporte de forma constante durante o tempo de incorporação. O aplicativo está pronto para passar para a implantação da Fase 2.
`DEPLOYED`	Todos os operadores foram implantados com o novo código (Fase 1 concluída). O aplicativo oferece suporte ao formato de tabela única, mas não o ativou.	A implantação da Fase 2 começa com `migrateAllEntitiesToLeaseTable` definido como `true`.
`PENDING`	Todos os operadores executam o novo código. A KCL migra dados das métricas de operador e das tabelas de estado do coordenador para a tabela de concessão.	Um tempo de incorporação padrão de 24 horas é decorrido após a conclusão da migração.
`COMPLETE`	A migração foi concluída. A KCL usa a tabela de concessão exclusivamente para todas as leituras e gravações. As antigas métricas de operador e as tabelas de estado do coordenador não são mais usadas.	Estado de terminal. Nenhuma outra transição ocorre.

Para obter informações detalhadas sobre cada estado, condições de transição e o comportamento completo da máquina de estado, consulte Máquina de estado de migração de tabela única da KCL no site do GitHub.

nota

O tempo de incorporação padrão entre os estados PENDING e COMPLETE é de 24 horas, mas você pode configurá-lo em até uma semana. Durante esse período, a KCL usa a tabela de concessão para todas as leituras e gravações, mas não exclui as tabelas antigas. Você deve excluir manualmente as tabelas antigas de métricas de operador e de estado do coordenador depois de confirmar que a migração foi bem-sucedida. A KCL não exclui essas tabelas automaticamente.

Métricas de migração

Com a KCL, você pode monitorar o andamento e a integridade da migração de tabela única usando as métricas do CloudWatch. Use essas métricas para confirmar se os operadores adotaram o novo código e para acompanhar a migração à medida que ela percorre os estados. Você também pode detectar falhas de leitura, gravação ou exclusão do DynamoDB durante a migração. As tabelas a seguir agrupam as métricas pela operação da KCL (dimensão de métrica) que as emite e por quando cada métrica é emitida.

O operador líder eleito emite continuamente as seguintes métricas, independentemente de uma migração estar em andamento:

Métricas emitidas pelo líder sempre
Operation	Métrica	Unidade	Descrição
`TableMigration`	`StatusOrdinal`	Nenhum	Ordinal do status de migração atual do DynamoDB: `0` = UNKNOWN, `1` = INIT, `2` = DEPLOYED, `3` = PENDING, `4` = COMPLETE.
`WorkerMetrics`	`FleetMinSupportCode`	Nenhum	Código mínimo de suporte em todos os operadores proprietários de concessão na frota.

O operador líder eleito emite as seguintes métricas somente enquanto uma migração está em andamento:

Métricas emitidas pelo líder durante a migração
Operation	Métrica	Unidade	Descrição
`TableMigration`	`Phase1Worker`	Contagem	Número de operadores que oferecem suporte à operação com uma única tabela do DynamoDB, mas que ainda não migraram para usar a tabela única.
`TableMigration`	`Phase2Worker`	Contagem	Número de operadores que migraram para a gravação em uma única tabela. Esses operadores ainda podem ler de várias tabelas até que a migração da tabela seja concluída.
`TableMigration`	`PrePhase1Worker`	Contagem	Número de operadores em uma versão anterior à 3.5 que não oferecem suporte à operação em uma única tabela do DynamoDB.
`TableMigration`	`WriteFault`	Contagem	`1` em caso de falha de gravação do DynamoDB, `0` em caso de sucesso.
`TableMigration`	`DeleteFault`	Contagem	`1` em caso de falha de exclusão do DynamoDB, `0` em caso de sucesso.
`TableMigration`	`CompletionFault`	Contagem	`1` quando a gravação transacional do status `COMPLETE` falha, `0` em caso de sucesso.
`TableMigrationAsyncMove`	`Success`	Contagem	`1` em uma movimentação transacional bem-sucedida das entradas do CoordinatorState, `0` em caso de falha.
`TableMigrationAsyncMove`	`Time`	Milissegundos	Duração da operação de movimentação assíncrona.
`TableMigrationAsyncMove`	`BatchCount`	Contagem	Número de lotes que foram movidos.

Todos os operadores emitem as seguintes métricas enquanto a migração está em andamento:

Métricas emitidas por todos os operadores durante a migração
Operation	Métrica	Unidade	Descrição
`TableMigration`	`ReadFault`	Contagem	`1` em caso de falha na leitura do `TableMigrationState` do DynamoDB, `0` em caso de sucesso.
`TableMigration`	`Time`	Milissegundos	Duração da execução da máquina de estado.
`TableMigrationInitialize`	`Success`	Contagem	`1` em uma inicialização bem-sucedida, `0` em caso de falha.
`TableMigrationInitialize`	`Time`	Milissegundos	Duração da operação de inicialização.

Use essas métricas para decidir quando avançar na migração. Quando StatusOrdinal é sempre 2 (DEPLOYED) e PrePhase1Worker é 0, todos os operadores oferecem suporte ao formato de tabela única, e você pode passar para a fase 2 da implantação da migração de tabelas. Depois que StatusOrdinal atingir 4 (COMPLETE), você pode excluir com segurança as tabelas herdadas.

Considerações sobre reversão

O suporte à reversão depende do TableMigrationStatus atual:

Durante a Fase 1 (TableMigrationStatus é DEPLOYED ou ainda não foi definido): você pode reverter com segurança para a versão anterior. O novo código é executado em um modo compatível com versões anteriores e nenhum dado foi gravado em entradas que não sejam de concessão na tabela de concessão.
Durante a Fase 2 (TableMigrationStatus é DEPLOYED ou PENDING): você pode voltar para a Fase 1. Os operadores voltam a usar as tabelas legadas (formato de várias tabelas) para métricas de operador e estado do coordenador. A migração é desfeita.
Após o estado COMPLETE: a reversão não é suportada. A KCL usa somente a tabela de concessão para todas as entidades. Mesmo que o código volte para a Fase 1, o operador continua usando a tabela de concessão para todas as entidades e a configuração é ignorada.

Atenção

Depois que a migração atinge o estado COMPLETE, o aplicativo opera exclusivamente no modo de tabela única. A configuração migrateAllEntitiesToLeaseTable é ignorada e a KCL não volta a usar tabelas separadas. O tempo de incorporação antes de passar para COMPLETE deve ser suficiente porque, depois disso, mesmo uma reversão de código não volta para várias tabelas.

Práticas recomendadas

Siga estas práticas recomendadas ao adotar o formato de tabela única:

Após a implantação da Fase 1, verifique se a entrada do estado do coordenador TableMigration3.5 atinge o status DEPLOYED. Garanta que não haja regressões antes de prosseguir para a Fase 2.
Monitore o TableMigrationStatus na entrada de estado do coordenador TableMigration3.5 para acompanhar o progresso nos estados DEPLOYED, PENDING e COMPLETE. O status é armazenado na tabela de estado do coordenador como uma entrada separada (não na tabela de concessão) até que a migração atinja COMPLETE.
O tempo de incorporação antes de passar para COMPLETE deve ser suficiente porque, depois disso, mesmo uma reversão de código não volta para várias tabelas. O aplicativo funciona somente no modo de tabela única.
Depois que a migração atingir o estado COMPLETE, exclua manualmente as antigas métricas de operador e tabelas de estado do coordenador. A KCL não exclui essas tabelas automaticamente — ela apenas deixa de usá-las.
Se você tiver configurado CoordinatorConfig.coordinatorStateTableConfig ou LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig, poderá remover essas configurações após a conclusão da migração. Essas configurações estão obsoletas na KCL 3.5 e em versões posteriores.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Avançar para a KCL 3.5.x+ na Fase 2 após uma reversão

Demonstração: DynamoDB Streams Kinesis Adapter