Como Criar e Gerenciar Tópicos Kafka Usando Linha de Comando

Como Criar e Gerenciar Tópicos Kafka Usando a Linha de Comando

Apache Kafka é uma plataforma distribuída de streaming de eventos frequentemente utilizada para pipelines de dados de alta vazão, análises em tempo real e comunicação de microsserviços. A unidade organizacional fundamental dentro do Kafka é o Tópico, uma categoria ou nome de feed para a qual os registros são publicados.

Embora existam ferramentas gráficas, a maneira mais robusta, confiável e comum de interagir e gerenciar a infraestrutura Kafka é diretamente através da interface de linha de comando (CLI). Dominar esses comandos essenciais é crucial para administradores e desenvolvedores responsáveis por manter um cluster Kafka saudável e eficiente. Este guia fornece um tutorial passo a passo sobre como usar o script kafka-topics.sh para executar as tarefas mais comuns de gerenciamento de tópicos.

Pré-requisitos e Configuração

Para executar os comandos neste guia, você deve ter acesso a uma máquina onde os binários do Kafka estão instalados. Todas as operações de gerenciamento de tópicos são realizadas usando o utilitário kafka-topics.sh, geralmente encontrado no diretório bin da sua instalação Kafka.

Todos os comandos exigem o endereço de pelo menos um broker Kafka, especificado usando a flag --bootstrap-server. Se você estiver usando uma versão mais antiga do Kafka (anterior à 2.2), ainda pode depender da flag --zookeeper, mas --bootstrap-server é o padrão recomendado e moderno.

Para os exemplos abaixo, assumiremos que o broker está rodando localmente na porta padrão:

# Standard Broker Address Placeholder
BROKER_ADDRESS="localhost:9092"

1. Criando um Novo Tópico Kafka

Criar um tópico requer a definição de seu nome, juntamente com dois parâmetros críticos que ditam seu comportamento e tolerância a falhas: o número de partições e o fator de replicação.

Parâmetros Essenciais

--topic <nome>: O nome do tópico.
--partitions <N>: O número de partições nas quais o tópico será dividido. Partições são as unidades de paralelismo e ordenação dentro de um tópico.
--replication-factor <N>: O número de cópias dos dados que serão mantidas entre diferentes brokers. Um fator de replicação de 1 significa nenhuma redundância.

Exemplo de Comando: Criando `sales-data`

Este comando cria um tópico chamado sales-data com 3 partições e um fator de replicação de 2 (o que significa que 2 cópias de cada partição existirão no cluster).

kafka-topics.sh --create --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS \n  --partitions 3 \n  --replication-factor 2

Dica: Em um ambiente de produção com N brokers, um fator de replicação de 3 é frequentemente recomendado para alta disponibilidade (permitindo a perda de dois brokers antes que ocorra perda de dados), e o número de partições deve ser ajustado com base na vazão antecipada e nas necessidades de paralelismo do consumidor.

2. Listando Todos os Tópicos

Para visualizar todos os tópicos atualmente disponíveis no cluster Kafka, use a flag --list.

Exemplo de Comando

kafka-topics.sh --list --bootstrap-server $BROKER_ADDRESS

Exemplo de Saída:

sales-data
logistics-stream
__consumer_offsets

3. Descrevendo a Configuração do Tópico

Verificar a configuração existente, a contagem de partições e a atribuição de brokers para um tópico específico é essencial para solução de problemas e verificação. Use a flag --describe.

Exemplo de Comando: Descrevendo `sales-data`

kafka-topics.sh --describe --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS

Interpretação da Saída:

A saída mostra a configuração tanto no nível do tópico quanto no nível da partição:

Topic: sales-data  PartitionCount: 3 ReplicationFactor: 2 Configs:
  Topic: sales-data  Partition: 0 Leader: 1 Replicas: 1,2 Isr: 1,2
  Topic: sales-data  Partition: 1 Leader: 2 Replicas: 2,0 Isr: 2,0
  Topic: sales-data  Partition: 2 Leader: 0 Replicas: 0,1 Isr: 0,1

Leader: O broker atualmente responsável por lidar com leituras/escritas para essa partição.
Replicas: A lista de brokers que possuem uma cópia dessa partição.
Isr (In-Sync Replicas): O subconjunto de réplicas que estão totalmente sincronizadas com o Leader. A alta disponibilidade exige que o Leader esteja no ISR.

4. Alterando Tópicos Existentes

Kafka oferece mecanismos limitados para alterar tópicos após a criação. As duas tarefas de alteração mais comuns são aumentar a contagem de partições e substituir as configurações padrão do broker.

A. Aumentando Partições

Partições só podem ser aumentadas, nunca diminuídas. Aumentar partições ajuda a escalar o paralelismo do consumidor.

Aviso: Aumentar partições altera a forma como as mensagens são mapeadas (hashed) para as partições. Se seus produtores dependem de garantias de ordenação baseadas em chave, aumentar as partições pode quebrar a entrega ordenada para chaves existentes.

Se sales-data atualmente tem 3 partições, podemos aumentá-lo para 5:

kafka-topics.sh --alter --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS \n  --partitions 5

B. Alterando a Configuração Específica do Tópico

Você pode substituir as configurações globais do broker (como tempo de retenção de mensagens ou políticas de limpeza) para tópicos individuais usando a flag --config.

Exemplo: Definindo um tempo de retenção de mensagens de 24 horas (86400000 milissegundos) para sales-data.

kafka-topics.sh --alter --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS \n  --config retention.ms=86400000

Para remover uma substituição de configuração específica e reverter para a configuração padrão do broker, use a flag --delete-config:

kafka-topics.sh --alter --topic sales-data \n  --bootstrap-server $BROAKER_ADDRESS \n  --delete-config retention.ms

5. Excluindo um Tópico Kafka

Tópicos que não estão mais em uso devem ser excluídos corretamente para recuperar espaço em disco e manter a higiene do cluster.

Habilitando a Exclusão de Tópicos

Por padrão, os brokers Kafka podem desabilitar a exclusão de tópicos por segurança. Antes de poder excluir um tópico, certifique-se de que a seguinte configuração esteja habilitada em seu arquivo server.properties em todos os brokers:

delete.topic.enable=true

Exemplo de Comando: Excluindo `old-stream`

Use a flag --delete para iniciar a remoção do tópico. A exclusão de tópicos é frequentemente assíncrona, o que significa que o comando envia a solicitação e a exclusão ocorre em segundo plano.

kafka-topics.sh --delete --topic old-stream \n  --bootstrap-server $BROKER_ADDRESS

Saída de Confirmação:

Deletion of topic old-stream initiated successfully.

Resumo dos Comandos de Gerenciamento de Tópicos

Ação	Flag(s)	Propósito	Parâmetros de Exemplo
Criar	`--create`	Inicializa um novo tópico.	`--partitions 5 --replication-factor 3`
Listar	`--list`	Mostra todos os tópicos no cluster.	N/A
Descrever	`--describe`	Visualiza a configuração e o layout atuais.	`--topic my-topic`
Alterar (Partições)	`--alter`	Aumenta o número de partições.	`--partitions N` (N > contagem atual)
Alterar (Config)	`--alter --config`	Substitui os padrões do broker para um tópico específico.	`--config retention.ms=...`
Excluir	`--delete`	Remove um tópico permanentemente.	`--topic my-topic`

Conclusão e Próximos Passos

A linha de comando continua sendo a interface mais poderosa e flexível para gerenciar seu cluster Kafka. Ao dominar o utilitário kafka-topics.sh, você obtém controle granular sobre os parâmetros de criação de tópicos, substituições de configuração e ações administrativas necessárias como exclusão e descrição.

Próximos Passos:

Pratique esses comandos em um ambiente de desenvolvimento ou staging.
Explore opções avançadas de configuração usando o comando --describe para ver a lista completa de propriedades configuráveis (por exemplo, cleanup.policy, max.message.bytes).
Aprenda os comandos CLI correspondentes para testes de produtor e consumidor (kafka-console-producer.sh e kafka-console-consumer.sh).