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

Os tópicos do Apache Kafka são onde seus produtores escrevem registros e seus consumidores os leem. Se você precisar criar, inspecionar, redimensionar ou excluir um tópico a partir de um terminal, a principal ferramenta é o kafka-topics.sh.

Ferramentas gráficas são úteis, mas os comandos CLI ainda são a maneira mais rápida de verificar o que o cluster está fazendo durante um incidente ou implantação. Este guia mostra os comandos de tópico que você usará com mais frequência e destaca os lugares onde o Kafka pode surpreendê-lo.

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, normalmente encontrado no diretório bin da sua instalação do Kafka.

Todos os comandos exigem o endereço de pelo menos um broker Kafka, especificado com --bootstrap-server. Clusters Kafka mais antigos ainda podem mostrar exemplos usando --zookeeper, mas a administração baseada em broker é o padrão atual.

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

# Placeholder do Endereço do Broker Padrão
BROKER_ADDRESS="localhost:9092"

1. Criando um Novo Tópico Kafka

Criar um tópico requer definir seu nome, junto 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 em 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 (significando que 2 cópias de cada partição existirão no cluster).

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

Dica: Em produção, um fator de replicação de 3 é comum porque mantém múltiplas cópias de cada partição em diferentes brokers. A tolerância a falhas real também depende do posicionamento do broker, min.insync.replicas e configurações de confirmação do produtor.

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 broker 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 \
  --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/gravações para aquela partição.
Replicas: A lista de brokers que possuem uma cópia daquela partição.
Isr (In-Sync Replicas): As réplicas que estão suficientemente atualizadas para serem elegíveis para failover seguro. Se o ISR encolher, verifique a saúde do broker, latência de disco e atraso de rede.

4. Alterando Tópicos Existentes

O Kafka fornece 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

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

Aviso: Aumentar partições altera como as mensagens são mapeadas (hash) para as partições. Se seus produtores dependem de garantias de ordenação baseadas em chave, aumentar 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 \
  --bootstrap-server $BROKER_ADDRESS \
  --partitions 5

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

Você pode ver exemplos mais antigos alterando configurações de tópico através de kafka-topics.sh --alter --config. Em clusters Kafka atuais, prefira kafka-configs.sh para alterações de configuração de tópico, pois é a ferramenta de administração dedicada para configurações dinâmicas.

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

kafka-configs.sh --bootstrap-server $BROKER_ADDRESS \
  --alter --entity-type topics --entity-name sales-data \
  --add-config retention.ms=86400000

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

kafka-configs.sh --bootstrap-server $BROKER_ADDRESS \
  --alter --entity-type topics --entity-name sales-data \
  --delete-config retention.ms

5. Excluindo um Tópico Kafka

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

Habilitando Exclusão de Tópico

Os brokers Kafka devem permitir exclusão antes que este comando possa remover dados. Em muitas implantações modernas, está habilitado, mas não assuma. Verifique a configuração do broker para:

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ópico é 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 \
  --bootstrap-server $BROKER_ADDRESS

Saída de Confirmação:

Exclusão do tópico old-stream iniciada com sucesso.

Resumo dos Comandos de Gerenciamento de Tópicos

Ação	Flag(s)	Propósito	Parâmetros de Exemplo
Criar	`--create`	Inicializar um novo tópico.	`--partitions 5 --replication-factor 3`
Listar	`--list`	Mostrar todos os tópicos no cluster.	N/A
Descrever	`--describe`	Visualizar configuração e layout atuais.	`--topic meu-topico`
Alterar (Partições)	`--alter`	Aumentar o número de partições.	`--partitions N` (N > contagem atual)
Alterar (Config)	`kafka-configs.sh --alter`	Substituir padrões do broker para um tópico específico.	`--add-config retention.ms=...`
Excluir	`--delete`	Remover um tópico permanentemente.	`--topic meu-topico`

Próximos Passos

Pratique esses comandos em um ambiente de desenvolvimento ou homologação.
Use kafka-configs.sh --describe antes e depois das alterações de configuração para saber quais valores são substituições de tópico.
Aprenda os comandos CLI correspondentes para teste de produtor e consumidor (kafka-console-producer.sh e kafka-console-consumer.sh).