Início Rápido do Apache Kafka - Instale o Kafka 4.2 com CLI e Exemplos Locais

O Apache Kafka 4.2.0 é a linha de versão suportada atualmente e representa a melhor base para um Quickstart moderno, pois o Kafka 4.x é totalmente livre de ZooKeeper e construído em torno do KRaft por padrão.

Este guia é um Quickstart prático e focado na linha de comando: instalando o Kafka, iniciando um broker local, aprendendo as ferramentas essenciais de CLI do Kafka e finalizando com dois exemplos completos que você pode colar diretamente no terminal.

O que é o Apache Kafka e para que ele é usado

O Apache Kafka é uma plataforma de streaming de eventos. Em termos práticos, streaming de eventos significa capturar dados de eventos em tempo real de diversas fontes (bancos de dados, sensores, aplicativos), armazenar as resultantes streams de forma durável e processá-las ou roteá-las em tempo real (ou posteriormente).

O Kafka reúne três capacidades principais em uma única plataforma: publicar e assinar streams de eventos, armazenar streams de forma durável pelo tempo necessário e processar streams conforme ocorrem ou retrospectivamente. Essa combinação é o motivo pelo qual o Kafka é utilizado em pipelines de dados em tempo real, integração, mensageria e análise de streaming.

Para contextualizar onde o Kafka se encaixa dentro de uma infraestrutura de dados mais ampla, consulte o pilar Infraestrutura de Dados para Sistemas de IA: Armazenamento de Objetos, Bancos de Dados, Pesquisa e Arquitetura de Dados de IA, que abrange armazenamento de objetos compatível com S3, arquitetura PostgreSQL, otimização do Elasticsearch e camadas de dados nativas de IA.

Se você está construindo na AWS e precisa de uma alternativa gerenciada, Construindo Microservices Orientados a Eventos com AWS Kinesis cobre a implementação de microsserviços orientados a eventos com Kinesis Data Streams.

Para processamento de streams com estado usando Kafka, consulte Apache Flink no K8s e Kafka: PyFlink, Go, operações e preços gerenciados.

Operacionalmente, o Kafka é um sistema distribuído de servidores e clientes que se comunicam por meio de um protocolo TCP de alto desempenho: os brokers armazenam e servem dados; os clientes (produtores e consumidores) escrevem e leem eventos, muitas vezes em grande escala e com tolerância a falhas.

Aqui estão alguns conceitos que você verá repetidamente na CLI:

• Tópicos organizam eventos. Um tópico é multi-produtor e multi-assinante, e os eventos podem ser lidos várias vezes porque o controle de retenção determina quando os dados antigos são descartados.
• Partições fragmentam (shard) um tópico entre brokers para escalabilidade; a ordenação é garantida por partição.
• Fator de replicação controla a tolerância a falhas. A documentação geralmente recomenda fatores de replicação de 2 ou 3 em produção (um Quickstart de desenvolvimento de nó único geralmente usa 1).

Instalar Apache Kafka

O Quickstart oficial do Kafka usa a versão binária (tarball) ou a imagem Docker oficial. Ambas são válidas para desenvolvimento local.

Pré-requisitos que você não deve pular

O Kafka 4.x requer Java moderno: para o servidor e ferramentas, o Java 17+ é a base para execução local, e o Kafka 4.0 removeu o suporte ao Java 8.

Se você está instalando o Kafka especificamente para aprender, vise um JDK suportado, como Java 17 ou 21. A página de suporte Java do Kafka lista Java 17, 21 e 25 como totalmente suportados, enquanto o Java 11 é suportado apenas para um subconjunto de módulos (clientes e streams).

Instalar a partir da versão binária oficial

O Quickstart oficial do Kafka 4.2.0 começa baixando e extraindo a distribuição binária:

tar -xzf kafka_2.13-4.2.0.tgz
cd kafka_2.13-4.2.0

Notas para leitores avançados:

• O “2.13” no nome do arquivo reflete a linha de construção Scala. Para binários Kafka 4.x, o Scala 2.13 é a linha de distribuição principal, e o Kafka 4.0 removeu o suporte ao Scala 2.12.
• Se você se preocupa com a integridade da cadeia de suprimentos, a página de downloads documenta explicitamente que você pode verificar os downloads usando os procedimentos publicados da Apache e as KEYS.

Instalar com Docker

O Kafka também fornece imagens Docker oficiais no Docker Hub. O Quickstart mostra que você pode puxar e executar o Kafka 4.2.0 assim:

docker pull apache/kafka:4.2.0
docker run -p 9092:9092 apache/kafka:4.2.0

Existe também uma linha de imagem “nativa” (baseada em imagem nativa GraalVM). A documentação do Kafka e a Proposta de Melhoria do Kafka para esta linha de imagem descrevem-na como experimental e destinada ao desenvolvimento local e testes, não à produção.

Nota de plataforma para usuários Windows

As distribuições do Kafka incluem scripts Windows (arquivos de lote). A documentação do Kafka nota historicamente que no Windows você usa bin\windows\ e scripts .bat em vez dos scripts Unix bin/ .sh.

Iniciar Kafka localmente com KRaft

Se você está perguntando “Preciso do ZooKeeper para executar o Apache Kafka”, a resposta moderna é não. O Kafka 4.0 é o primeiro lançamento principal projetado para operar completamente sem ZooKeeper, executando no modo KRaft por padrão, o que reduz a sobrecarga operacional para uso local e em produção.

Iniciar um broker local de nó único a partir do tarball extraído

O Quickstart 4.2 do Kafka usa três comandos:

1. Gerar um UUID do cluster
2. Formatar os diretórios de log
3. Iniciar o servidor

# Gerar um Cluster UUID
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Formatar Diretórios de Log (formato local standalone)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Iniciar o broker Kafka
bin/kafka-server-start.sh config/server.properties

Por que a etapa “format” importa no KRaft: A documentação de operações KRaft do Kafka explica que kafka-storage.sh random-uuid gera o ID do cluster e que cada servidor deve ser formatado com kafka-storage.sh format. Uma das razões dadas é que a formatação automática pode ocultar erros, especialmente em torno do log de metadados, então a formatação explícita é preferida.

O que você está executando neste Quickstart

Para desenvolvimento local, o Kafka pode executar em uma configuração simplificada “combinada” (controladores e brokers juntos). A documentação KRaft do Kafka destaca servidores combinados como mais simples para desenvolvimento, mas não recomendados para ambientes de implantação críticos (onde você quer controladores isolados e escaláveis independentemente).

Para clusters “reais”, os controladores e brokers KRaft têm papéis separados (process.roles), e os controladores são geralmente implantados como um quórum de 3 ou 5 nós (a disponibilidade depende da maioria estar viva).

Essenciais da CLI do Kafka e principais parâmetros de linha de comando

O Kafka vem com muitas ferramentas de CLI sob bin/. A documentação oficial de operações enfatiza duas propriedades úteis:

• As ferramentas comuns vivem no diretório bin/ da distribuição.
• Cada ferramenta imprime seu uso completo de linha de comando quando executado sem argumentos.

Também importante para Kafka 4.x: Comandos AdminClient não aceitam mais --zookeeper. A documentação de compatibilidade do Kafka destaca que, a partir do Kafka 4.0, você deve usar --bootstrap-server para interagir com o cluster.

Sinalizadores de conexão Kafka que você usará constantemente

A maioria das ferramentas precisa de um ponto de entrada do cluster:

• --bootstrap-server host:port
  Use isso para operações de tópicos, grupos de consumidores e a maioria dos comandos voltados para o broker. É a substituição canônica para fluxos de trabalho de administração baseados em ZooKeeper no Kafka 4.x.

O KRaft introduz endpoints de broker vs controlador para algumas ferramentas. Por exemplo, kafka-features.sh e partes da ferramenta de metadados podem usar endpoints de controlador, enquanto muitas operações de administração usam endpoints de broker. A página de operações KRaft mostra ambos os estilos em exemplos.

Gerenciamento de tópicos com kafka-topics.sh

Você usará kafka-topics.sh para o ciclo de vida principal:

• Criar, descrever, listar tópicos (Quickstart mostra --create, --describe, --topic).
• Especifique escala e durabilidade via partições e fator de replicação. O guia de operações mostra --partitions e --replication-factor e explica como eles afetam a escalabilidade e a tolerância a falhas.
• Adicione sobrescritas por tópico no momento da criação com --config key=value (documentação de configuração do tópico mostra exemplos concretos).

Um bom comando de criação “voltado para produção” parece com isso (esta forma exata é usada na documentação oficial de operações):

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic my_topic_name \
  --partitions 20 --replication-factor 3 \
  --config x=y

Produzir e consumir com clientes de console

O Quickstart usa o produtor e consumidor de console porque eles são rápidos para validação e testes de fumaça:

• kafka-console-producer.sh --topic ... --bootstrap-server ...
• kafka-console-consumer.sh --topic ... --from-beginning --bootstrap-server ...

O Kafka 4.2 também inclui melhorias de consistência da CLI. Nas notas de atualização:

• kafka-console-producer deprecia --max-partition-memory-bytes e recomenda --batch-size em vez disso.
• kafka-console-consumer deprecia --property (propriedades do formatador) em favor de --formatter-property.
• kafka-console-producer deprecia --property (propriedades do leitor de mensagens) em favor de --reader-property.

Se você mantém runbooks internos, essas notas valem a pena atualizar agora, antes que o Kafka 5.0 remova as bandeiras deprecadas.

Inspeção de lag do consumidor com kafka-consumer-groups.sh

Para sistemas reais, “Meu consumidor está acompanhando?” é uma pergunta diária. O guia de operações demonstra:

• Listar grupos: --list
• Descrever um grupo com offsets e lag: --describe --group ...
• Descrever membros e atribuições: --members e --verbose
• Excluir grupos: --delete
• Resetar offsets com segurança: --reset-offsets

Exemplo:

bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group

Uma ressalva de configuração para Docker local e clientes remotos

Se você executar Kafka em containers ou atrás de balanceadores de carga, eventualmente encontrará a necessidade de configurar os listeners corretamente. A documentação de configuração do broker do Kafka explica advertised.listeners como os endereços que os brokers anunciam aos clientes e outros brokers, particularmente quando o endereço de vinculação não é o endereço que os clientes devem usar.

Exemplos de Quickstart que você pode executar agora

Os exemplos abaixo são deliberadamente baseados em CLI para que você possa validar uma configuração local do Kafka antes de escrever qualquer código de aplicativo.

Exemplo: executar um tópico e transmitir mensagens do início ao fim

Este é o fluxo canônico “criar, produzir, consumir” do Quickstart Kafka 4.2.

Abra o terminal A e crie um tópico:

bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092

Agora descreva-o (opcional, mas útil quando você está aprendendo sobre partições e fator de replicação):

bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092

Abra o terminal B e inicie um produtor:

bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092

Digite algumas linhas (cada linha se torna um evento), então deixe o produtor rodando:

Este é o meu primeiro evento
Este é o meu segundo evento

Abra o terminal C e inicie um consumidor desde o início:

bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092

Você deve ver as mesmas linhas impressas.

Por que isso valida mais do que “funciona”: O Quickstart do Kafka explica que os brokers armazenam eventos de forma durável e que eventos podem ser lidos várias vezes e por múltiplos consumidores. Essa durabilidade é o motivo pelo qual este padrão de Quickstart é a primeira coisa que você deve fazer após qualquer instalação ou atualização.

Exemplo: executar um pipeline simples do Kafka Connect de arquivo para tópico para arquivo

O Kafka Connect responde à pergunta recorrente “Como movo dados para dentro e para fora do Kafka sem escrever produtores e consumidores personalizados para tudo”. A visão geral do Kafka Connect descreve-o como uma ferramenta para streaming escalável e confiável entre o Kafka e outros sistemas, via conectores.

O Quickstart Kafka 4.2 inclui uma demonstração local mínima do Connect usando os conectores de fonte e sink de arquivo.

Do seu diretório Kafka, primeiro defina o caminho do plugin do worker para incluir o jar do conector de arquivo fornecido:

echo "plugin.path=libs/connect-file-4.2.0.jar" >> config/connect-standalone.properties

Crie um arquivo de entrada minúsculo:

echo -e "foo\nbar" > test.txt

Inicie o worker do Connect no modo standalone com configurações de conector de fonte e sink:

bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/connect-file-source.properties \
  config/connect-file-sink.properties

O que deve acontecer (e por que é útil):

• O conector de fonte lê linhas de test.txt e as produz para o tópico connect-test.
• O conector de sink lê de connect-test e escreve em test.sink.txt.

Verifique o arquivo de sink:

more test.sink.txt

Você deve ver:

foo
bar

Você também pode verificar o tópico diretamente:

bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning

Este segundo exemplo é um ótimo construtor de memória muscular porque também ensina onde a configuração do Connect reside (configuração do worker mais configurações do conector) e mostra um loop mínimo “ingestão, armazenamento, exportação”.

Solução de problemas e próximos passos

A maioria dos problemas “Kafka Quickstart não inicia” cai em um pequeno conjunto de causas raiz.

Broker falha ao iniciar

Comece com os requisitos oficiais:

• O Quickstart Kafka 4.2 exige explicitamente Java 17+. Se você estiver em um JDK mais antigo, corrija isso primeiro.
• No modo KRaft, a formatação de armazenamento é uma etapa explícita obrigatória. Se você pular kafka-storage.sh format, provavelmente verá falhas de inicialização ou erros de metadados.

Se você experimentou e agora quer uma lousa em branco, o Quickstart do Kafka mostra como excluir os diretórios de dados locais usados na demonstração:

rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs

Comandos de CLI falham mesmo que o broker esteja rodando

No Kafka 4.x, valide que você está usando --bootstrap-server (não --zookeeper). A documentação de compatibilidade do Kafka destaca explicitamente a remoção de --zookeeper dos comandos AdminClient a partir do Kafka 4.0.

Surpresas de rede Docker

Se o Kafka estiver no Docker e sua ferramenta de cliente estiver fora do Docker (ou em outra máquina), você pode precisar de anúncio de listener correto. A documentação de configuração do broker explica que advertised.listeners é usado quando os endereços aos quais os clientes devem se conectar diferem dos endereços de vinculação (listeners).

Para onde ir após o Quickstart

Se você completou os exemplos neste post, você já respondeu às pesquisas iniciais mais comuns:

• para que o Kafka é usado (streaming de eventos do início ao fim)
• como instalar o Kafka localmente (tarball ou Docker)
• por que o ZooKeeper sumiu e o KRaft é o padrão no 4.x
• quais ferramentas de CLI importam dia a dia (tópicos, produtor, consumidor, grupos)

A partir daqui, os próximos passos mais valiosos geralmente são:

• Leia a “Introdução” do Kafka para modelos mentais mais profundos de tópicos, partições e replicação.
• Explore o Quick Start do Kafka Streams se você quiser um primeiro aplicativo de processamento (o Quickstart do Streams demonstra a execução da demo WordCount e a inspeção de resultados com o consumidor de console).