Introdução ao Apache Kafka - Instalação do Kafka 4.2 com CLI e Exemplos Locais

A linha de lançamento 4.2.0 do Apache Kafka é a atualmente suportada e constitui a melhor base para um guia de início rápido moderno, uma vez que o Kafka 4.x é totalmente livre de ZooKeeper e construído em torno do KRaft por padrão.

Este guia é um início rápido prático, focado na linha de comandos: instalar o Kafka, iniciar um broker local, aprender as ferramentas essenciais de CLI do Kafka e concluir com dois exemplos de ponta a ponta que pode copiar e colar no seu terminal.

O que é o Apache Kafka e para que serve

O Apache Kafka é uma plataforma de streaming de eventos. Em termos práticos, streaming de eventos significa capturar dados de eventos em tempo real a partir de fontes (bases de dados, sensores, aplicações), armazenar os fluxos resultantes de forma durável e processá-los ou encaminhá-los em tempo real (ou posteriormente).

O Kafka reúne três capacidades principais numa única plataforma: publicar e subscrever fluxos de eventos, armazenar fluxos de forma durável durante o tempo necessário e processar fluxos à medida que ocorrem ou retrospectivamente. Esta combinação é a razão pela qual o Kafka é utilizado para pipelines de dados em tempo real, integração, messagens e análise de streaming.

Para compreender o contexto em que o Kafka se insere numa infraestrutura de dados mais ampla, consulte o pilar Infraestrutura de Dados para Sistemas de IA: Armazenamento de Objetos, Bases de Dados, Pesquisa & Arquitetura de Dados de IA, que cobre armazenamento de objetos compatível com S3, arquitetura PostgreSQL, otimização do Elasticsearch e camadas de dados nativas de IA.

Se estiver a construir sobre AWS e precisar de uma alternativa gerida, Construção de Microsserviços Orientados a Eventos com AWS Kinesis cobre a implementação de microsserviços orientados a eventos com Kinesis Data Streams.

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

Para serviços que escrevem numa base de dados antes de publicar no Kafka, o padrão de caixa de saída transacional garante que os eventos nunca são perdidos entre o commit da base de dados e a chamada de produção do Kafka.

Operacionalmente, o Kafka é um sistema distribuído de servidores e clientes que comunicam através 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.

Alguns conceitos que verá repetidamente na CLI:

• Tópicos organizam eventos. Um tópico é multi-produtor e multi-subscritor, e os eventos podem ser lidos múltiplas vezes porque a retenção controla quando os dados antigos são descartados.
• Partições dividem um tópico entre brokers para escalabilidade; a ordenação é garantida por partição.
• Fator de replicação controla a tolerância a falhas. Os exemplos de documentação recomendam comumente fatores de replicação de 2 ou 3 em produção (um início rápido de desenvolvimento de nó único tipicamente usa 1).

Instalar o Apache Kafka

O início rápido oficial do Kafka usa o lançamento binário (tarball) ou a imagem Docker oficial. Ambos são válidos para desenvolvimento local.

Pré-requisitos que não deve ignorar

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 estiver a instalar o Kafka especificamente para o aprender, vise uma JDK suportada como o Java 17 ou 21. A página de suporte Java do Kafka lista o 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 do lançamento binário oficial

O início rápido oficial para o Kafka 4.2.0 começa por descarregar e extrair 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 ficheiro reflete a linha de construção Scala. Para binários do 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 se preocupa com a integridade da cadeia de suprimentos, a página de descarregamentos documenta explicitamente que pode verificar os descarregamentos usando os procedimentos e chaves (KEYS) publicados pela Apache.

Instalar com Docker

O Kafka também fornece imagens Docker oficiais no Docker Hub. O início rápido mostra que pode obter 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 imagens “nativas” (baseada em imagem nativa GraalVM). A documentação do Kafka e a Proposta de Melhoria do Kafka para esta linha de imagens descrevem-na como experimental e destinada a desenvolvimento e teste locais, não para produção.

Nota de plataforma para utilizadores Windows

As distribuições do Kafka incluem scripts Windows (ficheiros batch). Os documentos do Kafka notam historicamente que no Windows deve usar bin\windows\ e scripts .bat em vez dos scripts Unix bin/ .sh.

Iniciar o Kafka localmente com KRaft

Se a pergunta é “Preciso do ZooKeeper para executar o Apache Kafka”, a resposta moderna é não. O Kafka 4.0 é o primeiro lançamento principal desenhado para operar totalmente 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 início rápido 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 UUID do Cluster
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

Porque é que o passo “format” importa no KRaft: A documentação de operações do 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 esconder erros, especialmente em torno do log de metadados, pelo que a formatação explícita é preferível.

O que está a executar neste início rápido

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

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

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

O Kafka é fornecido com muitas ferramentas de CLI sob bin/. Os documentos oficiais de operações enfatizam duas propriedades úteis:

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

Também importante para o Kafka 4.x: Os comandos AdminClient já não aceitam --zookeeper. A documentação de compatibilidade do Kafka nota que, a partir do Kafka 4.0, deve usar --bootstrap-server para interagir com o cluster.

Bandeiras de conexão do Kafka que usará constantemente

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

• --bootstrap-server host:port
  Use isto 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 das ferramentas de metadados podem usar endpoints de controlador, enquanto muitas operações de administração usam endpoints de broker. A página de operações do KRaft mostra ambos os estilos nos exemplos.

Gestão de tópicos com kafka-topics.sh

Usará kafka-topics.sh para o ciclo de vida principal:

• Criar, descrever, listar tópicos (o início rápido mostra --create, --describe, --topic).
• Especificar escala e durabilidade via partições e fator de replicação. O guia de operações mostra --partitions e --replication-factor e explica como afetam a escalabilidade e tolerância a falhas.
• Adicionar substituições por tópico no momento da criação com --config key=value (os documentos de configuração do tópico mostram exemplos concretos).

Um bom comando de criação “mentalidade de produção” parece com isto (esta forma exata é usada nos documentos oficiais 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 consola

O início rápido usa o produtor e consumidor de consola porque 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 formatação) em favor de --formatter-property.
• kafka-console-producer deprecia --property (propriedades do leitor de mensagens) em favor de --reader-property.

Se mantém manuais de procedimentos internos, estas notas valem a pena atualizar agora, antes que o Kafka 5.0 remova as bandeiras deprecadas.

Inspeccionar atraso do consumidor com kafka-consumer-groups.sh

Para sistemas reais, “O meu consumidor está a acompanhar” é uma questão diária. O guia de operações demonstra:

• Listar grupos: --list
• Descrever um grupo com offsets e atraso: --describe --group ...
• Descrever membros e atribuições: --members e --verbose
• Apagar grupos: --delete
• Resetear 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 executar o Kafka em contentores ou atrás de load balancers, eventualmente encontrará a necessidade de definir os listeners corretamente. Os documentos de configuração do broker do Kafka explicam advertised.listeners como os endereços que os brokers anunciam aos clientes e outros brokers, particularmente quando o endereço de ligação não é o endereço que os clientes devem usar.

Exemplos de início rápido que pode executar agora

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

Exemplo executar um tópico e transmitir mensagens de ponta a ponta

Este é o fluxo canónico “criar, produzir, consumir” do início rápido do 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 está a aprender 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 torna-se um evento), depois deixe o produtor a correr:

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

Deveria ver as mesmas linhas impressas.

Porque é que isto valida mais do que “funciona”: O início rápido do Kafka explica que os brokers armazenam eventos de forma durável e que os eventos podem ser lidos múltiplas vezes e por múltiplos consumidores. Essa durabilidade é a razão pela qual este padrão de início rápido é a primeira coisa que deve fazer após qualquer instalação ou atualização.

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

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 fiável entre o Kafka e outros sistemas, via conetores.

O início rápido do Kafka 4.2 inclui uma demonstração local mínima de Connect usando os conetores de fonte e destino de ficheiro.

A partir do seu diretório Kafka, primeiro defina o caminho do plugin do worker para incluir o jar do conetor de ficheiro fornecido:

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

Crie um ficheiro de entrada pequeno:

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

Inicie o worker Connect em modo standalone com configuração de conetor de fonte e destino:

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

O que deve acontecer (e porquê é útil):

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

Verifique o ficheiro de destino:

more test.sink.txt

Deveria ver:

foo
bar

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 grande construtor de memória muscular porque também ensina onde fica a configuração do Connect (configuração do worker mais configurações do conetor) e mostra um loop mínimo “ingestir, armazenar, exportar”.

Resolução de problemas e próximos passos

A maioria dos problemas “o início rápido do Kafka não inicia” cai num pequeno conjunto de causas raiz.

O broker falha ao iniciar

Comece com os requisitos oficiais:

• O início rápido do Kafka 4.2 requer explicitamente Java 17+. Se estiver num JDK mais antigo, corrija isso primeiro.
• No modo KRaft, a formatação do armazenamento é um passo explícito obrigatório. Se ignorar kafka-storage.sh format, é provável que veja falhas de arranque ou erros de metadados.

Se experimentou e agora quer uma folha em branco, o início rápido do Kafka mostra como apagar os diretórios de dados locais usados na demonstração:

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

Comandos da CLI falham mesmo com o broker a correr

No Kafka 4.x, valide que está a usar --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 do Docker

Se o Kafka está no Docker e a sua ferramenta de cliente está fora do Docker (ou noutra máquina), pode precisar de anúncio de listener correto. Os documentos de configuração do broker explicam que advertised.listeners é usado quando os endereços que os clientes devem conectar diferem dos endereços de ligação (listeners).

Para onde ir após o início rápido

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

• para que serve o Kafka (streaming de eventos de ponta a ponta)
• como instalar o Kafka localmente (tarball ou Docker)
• porquê o ZooKeeper desapareceu e o KRaft é o padrão no 4.x
• quais as ferramentas de CLI que importam dia a dia (tópicos, produtor, consumidor, grupos)

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

• Ler a “Introdução” do Kafka para modelos mentais mais profundos de tópicos, partições e replicação.
• Explorar o Início Rápido do Kafka Streams se quiser uma primeira aplicação de processamento (o início rápido do Streams demonstra executar a demonstração WordCount e inspecionar resultados com o consumidor de consola).