Kafka com Docker explicado: configuração, boas práticas e dicas

No mundo dos pipelines de dados modernos e de microsserviços, o Apache Kafka se destaca como a solução ideal para lidar com fluxos de eventos em tempo real e integrar sistemas distribuídos. À medida que mais times de engenharia avançam para arquiteturas escaláveis e orientadas a eventos, o Kafka se torna central para a movimentação confiável de dados. 

Em paralelo a essa tendência, o Docker surgiu como a principal forma de desenvolvedores gerenciarem, compartilharem e implantarem serviços complexos sem se preocupar com ambientes inconsistentes ou problemas locais. 

Usando Docker para executar o Kafka, os times conseguem subir rapidamente clusters com cara de produção para testes, provas de conceito e até mesmo cargas de trabalho em produção. 

Este artigo é voltado para desenvolvedores backend de nível intermediário, engenheiros de DevOps e qualquer pessoa envolvida na gestão de plataformas de dados que queira tornar o trabalho com Kafka mais simples e reprodutível.

Se você é novo em Kafka ou Docker, confira nosso curso Introduction to Apache Kafka ou o guia Docker for Beginners: A Practical Guide to Containers.

O que é Kafka e por que usar Docker?

O Apache Kafka é uma plataforma de streaming distribuída projetada para mensageria com alta taxa de transferência, tolerância a falhas e escalabilidade. 

Ele atua como um pipeline durável e de alta velocidade entre produtores e consumidores de dados. Sempre que você precisar conectar microsserviços, orquestrar fluxos de dados ou processar análises em tempo real, o Kafka costuma ser a ferramenta certa.

Você pode aprender a criar aplicações de processamento de dados em tempo real com Kafka Streams no nosso Kafka Streams Tutorial. O tutorial aborda conceitos essenciais, implementações em Java e Python e exemplos passo a passo para construir aplicações de streaming escaláveis.

Executar o Kafka pode ser complexo. Mesmo engenheiros experientes acham a combinação de brokers, tópicos, partições e componentes necessários como Zookeeper ou KRaft desafiadora. 

O Docker simplifica o processo ao empacotar binários, dependências e configurações em containers. 

Com Docker, os engenheiros podem iniciar um cluster Kafka em qualquer máquina, compartilhar configurações idênticas com colegas e evitar a famosa dor de cabeça do "funciona na minha máquina". O Kafka em Docker é especialmente popular para:

• Desenvolvimento e testes locais, onde subir e derrubar serviços rapidamente é valioso
• Ambientes de integração isolados em pipelines de CI/CD
• Simular clusters com vários brokers em um único host
• Ambientes de treinamento e demonstração

Explore o Apache Kafka com nosso guia Apache Kafka for Beginners. Aprenda o básico, comece a usar e descubra recursos avançados e aplicações reais dessa poderosa plataforma de streaming de eventos.

Fundamentos do Kafka no Docker

Antes de entrar na orquestração, vale destrinchar as partes técnicas do Kafka e como o Docker ajuda a recriar sua natureza distribuída em um laptop ou servidor. 

Como você vai ver no nosso tutorial Learn Docker from Scratch, o Docker é uma ferramenta popular para simplificar a implantação, escalabilidade e gestão de aplicações como o Kafka por meio de conteinerização.

Noções básicas da arquitetura do Kafka

A espinha dorsal do Kafka é o broker: um processo de servidor que armazena, recebe e entrega mensagens. Cada cluster pode ter vários brokers, distribuindo dados e carga. 

Dentro de cada broker existem tópicos (canais nomeados para organizar mensagens) e partições (subcanais que espalham eventos por vários servidores para paralelismo e durabilidade). Produtores escrevem dados em tópicos, enquanto consumidores assinam e processam essas mensagens.

Coordenação é essencial. Tradicionalmente, o Kafka dependia do Zookeeper para lidar com metadados de brokers, liderança de partições e a saúde geral do cluster. Implementações mais novas podem usar o modo KRaft, que internaliza essa coordenação no próprio Kafka, eliminando a dependência do Zookeeper. O ZooKeeper foi descontinuado na versão 3.5 e deve ser removido na 4.0.

Aprenda a conteinerizar aplicações de machine learning com Docker e Kubernetes usando nosso tutorial How to Containerize an Application Using Docker. 

Modo KRaft: simplificando a arquitetura do Kafka

A partir da versão 2.8, o Kafka introduziu o modo KRaft, permitindo gerenciar metadados internamente sem depender do Zookeeper, sendo considerado pronto para produção na versão 3.3. Essa mudança simplifica as implantações e reduz o número de componentes a serem gerenciados.

Para configurar o Kafka em modo KRaft usando Docker Compose:

version: '3.8'
services:
  kafka:
    image: apache/kafka:latest
    container_name: kafka
    ports:
      - "9092:9092"
      - "9093:9093"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9093
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LOG_DIRS: /var/lib/kafka/data
      KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true"
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_LOG_RETENTION_HOURS: 168
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      CLUSTER_ID: "Mk3OEYBSD34fcwNTJENDM2Qk"
    volumes:
      - ./data:/var/lib/kafka/data

Essa configuração cria um cluster Kafka de nó único em modo KRaft, eliminando a necessidade do Zookeeper.

Essenciais de Docker

Para executar Kafka com Docker, você só precisa de alguns itens: Docker Engine (o runtime) e, geralmente, Docker Compose para gerenciar múltiplos containers. 

Arquivos Compose permitem especificar vários serviços (Kafka, Zookeeper, Kafka UI etc.), suas redes, variáveis de ambiente e quaisquer montagens de armazenamento. A rede do Docker possibilita emular clusters com vários brokers, mesmo em uma única máquina, dando a cada broker seu container, hostnames e portas.

Uma das melhores formas de se familiarizar com Docker é com projetos práticos. Treine usando estas 10 Docker Project Ideas. 

Configurando o Kafka com Docker Compose

Docker Compose costuma ser a forma preferida de executar aplicações que exigem vários containers interagindo. Em vez de lidar com scripts de shell ou comandos manuais, o Compose permite definir todos os serviços e seus vínculos em um único arquivo YAML. 

Essa abordagem reduz a deriva de configuração, acelera o onboarding e garante que todos usem a mesma stack no desenvolvimento.

Configuração mínima com Compose

Aqui está um docker-compose.yml básico que inicia o Kafka e o Zookeeper para desenvolvimento local:

version: '3'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
    ports:
      - "2181:2181"
  kafka:
    image: confluentinc/cp-kafka:latest
    depends_on:
      - zookeeper
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
    ports:
      - "9092:9092"
    volumes:
      - kafka_data:/var/lib/kafka/data
volumes:
  kafka_data:

Essa configuração mínima mapeia as portas relevantes, conecta o Kafka ao Zookeeper e monta um volume do Docker para que as mensagens não sumam se os containers reiniciarem. Use variáveis de ambiente para configurar a identidade do broker, os endereços de listeners e os endpoints de conexão entre serviços.

Entender bem o Kafka é essencial para mandar bem em entrevistas de engenharia de dados. Prepare-se para a sua próxima entrevista com nossa lista de perguntas e respostas usando estas 20 Kafka Interview Questions for Data Engineers. 

Configuração estendida

Ambientes profissionais costumam adicionar ferramentas como Kafka UI, Schema Registry ou REST Proxy para facilitar a gestão e a inspeção de mensagens. Elas podem ser incluídas no bloco de services do seu arquivo compose. Por exemplo:

kafka-ui:
  image: provectuslabs/kafka-ui:latest
  ports:
    - "8080:8080"
  environment:
    KAFKA_CLUSTERS_0_NAME: "Local"
    KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: "kafka:9092"

Persistir tópicos e logs do Kafka entre reinicializações é essencial para testar cenários de recuperação ou jobs de longa duração. Sempre monte volumes do Docker em /var/lib/kafka/data para cada broker e em /var/lib/zookeeper para o Zookeeper, se estiver em uso.

Escolher a imagem certa é fundamental. Aqui vai um resumo rápido:

O tutorial How to Learn Apache Kafka in 2025 aprofundará mais detalhes sobre o Kafka, incluindo 

• O que torna o Apache Kafka popular?
• Principais recursos do Apache Kafka
• Diversas aplicações do Apache Kafka

Interagindo com o Kafka no Docker

Assim que o Kafka estiver rodando via Docker Compose, você pode criar tópicos e enviar dados imediatamente, como faria em qualquer implantação padrão.

Acesso via CLI e comandos do Kafka

Use docker-compose exec ou docker exec para rodar as ferramentas de CLI do Kafka. Por exemplo, para criar um tópico, execute:

docker-compose exec kafka kafka-topics.sh --create --topic demo --bootstrap-server localhost:9092

Você também pode usar kafka-console-producer.sh e kafka-console-consumer.sh da mesma forma. Isso cria um ciclo de feedback rápido para testes de integração ou experimentação sem poluir seu ambiente local.

Acesso programático a partir de apps

Aplicações e scripts podem se conectar ao seu Kafka conteinerizado usando os bootstrap servers anunciados pelo host. Para apps locais, defina bootstrap.servers=localhost:9092 ou equivalente. 

Clientes comuns incluem as bibliotecas oficiais do Kafka para Python, Java, NodeJS e Go. Garanta que a pilha de rede da sua aplicação alcance as portas e endereços corretos.

Rede no Docker e conectividade do Kafka

A configuração de rede do Kafka frequentemente traz desafios. Entender listeners internos e externos e como expor serviços é vital.

Listeners internos vs. externos

Brokers do Kafka usam listeners para controlar conexões de clientes. Dois setups comuns são:

• PLAINTEXT://:9092 para tráfego local sem segurança, especialmente em dev
• SSL ou SASL_SSL para conexões criptografadas ou autenticadas

No docker-compose, exponha as portas corretas e garanta que KAFKA_ADVERTISED_LISTENERS corresponda ao host e porta reais que suas apps usam. Se estiver em uma VM ou nuvem, ajuste para o IP público e a porta mapeada.

Configurando múltiplos listeners para diferentes acessos de clientes

Em ambientes Docker, é comum configurar múltiplos listeners para lidar com diferentes cenários de acesso de clientes:

environment:
  KAFKA_LISTENERS: INTERNAL://0.0.0.0:29092,EXTERNAL://0.0.0.0:9092
  KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://localhost:9092
  KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT
  KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL

Esse setup permite que clientes internos do Docker se conectem via o listener INTERNAL e clientes externos se conectem via o listener EXTERNAL.

Solucionando problemas de conectividade

Erros comuns incluem “broker not available”, “connection refused” ou timeouts no cliente. Verifique:

• Se as portas estão expostas e mapeadas corretamente
• Se os advertised listeners do broker batem com o endereço que o cliente usa
• Se todos os containers estão saudáveis com docker-compose ps
• Se a resolução de DNS funciona entre containers (use o nome do serviço, por exemplo, kafka:9092)
• Use docker network inspect para depurar links entre containers

Kafka com Docker em ambientes parecidos com produção

Além dos testes locais, ambientes de Kafka conteinerizados também ajudam em staging e CI/CD.

Estratégias de orquestração de containers

Orquestradores como Docker Swarm e Kubernetes conseguem gerenciar setups de Kafka com vários brokers, atualizações contínuas (rolling updates) e discovery de serviços. Cada broker fica em seu container, com armazenamento persistente acoplado. 

No Kubernetes, StatefulSets cuidam da implantação ordenada e criam nomes de DNS estáveis para cada broker.

Logs e monitoramento

Direcione os logs do Kafka para o driver de logs do Docker ou para um armazenamento externo para análise. Muitos times enviam logs para Elasticsearch, Loki ou Splunk para troubleshooting. Combine Kafka em Docker com Prometheus e Grafana para monitorar o cluster.

Dicas de otimização para Kafka no Docker

A performance do Kafka depende de uma gestão cuidadosa de recursos e armazenamento.

Alocação de recursos

Dê a cada container de broker CPU, RAM e disco suficientes para imitar o mais perto possível o ambiente de produção. Ajuste limites de recursos do Docker e passe opções da JVM com KAFKA_JVM_PERFORMANCE_OPTS para heap e coleta de lixo.

Armazenamento persistente

Sempre use volumes do Docker ou bind mounts para /var/lib/kafka/data e /var/lib/zookeeper. Armazenar dados dentro do container significa perdê-los ao reiniciar, o que inviabiliza testes de durabilidade. Alta taxa de escrita em disco é crítica para performance sustentada, especialmente em testes de carga em CI/CD.

Boas práticas e armadilhas comuns

Estabilidade, manutenção e produtividade do time se beneficiam de algumas boas práticas.

Gestão de configuração

Gerencie segredos e configurações externamente com arquivos .env ou diretórios de configuração montados. Nunca codifique dados sensíveis diretamente no YAML do compose. Para setups reutilizáveis, considere ferramentas de template ou frameworks de gestão de configuração.

Erros comuns

Como evitar erros recorrentes

• Não armazene dados dentro dos containers; sempre monte volumes
• Verifique conflitos de porta no seu host
• Evite senhas padrão de admin; proteja portas expostas, mesmo em desenvolvimento local
• Mantenha as imagens Docker atualizadas; corrija CVEs e dependências obsoletas

Reforçando a segurança do Kafka

Para proteger sua implantação do Kafka:

• Habilite criptografia TLS: Proteja os dados em trânsito configurando SSL/TLS para todas as conexões.
• Implemente autenticação: Use mecanismos SASL (por exemplo, SCRAM, GSSAPI) para autenticar clientes.
• Configure autorização: Defina listas de controle de acesso (ACLs) para controlar permissões dos clientes.
• Gire credenciais regularmente: Altere senhas e chaves periodicamente para reduzir riscos.
• Monitore e faça auditoria: Habilite logs de auditoria para rastrear acessos e mudanças no cluster

Conclusão

O Docker torna surpreendentemente fácil iniciar, ajustar e experimentar clusters do Apache Kafka para integração, aprendizado ou até testes semelhantes aos de produção. Os containers isolam você de problemas do SO host e de incompatibilidades de dependências, garantindo que seus ambientes de dev e teste correspondam ao esperado. À medida que você evolui de clusters locais simples para plataformas de Kafka orquestradas, investir em setups robustos de Docker e em boas práticas vai economizar tempo e evitar frustrações do seu time. 

Explore mais sobre Kafka e Docker em um dos nossos cursos completos: 

• Introduction to Apache Kafka
• Professional Data Engineer in Python
• Containerization and Virtualization Concepts
• Containerization and Virtualization with Docker and Kubernetes
• Intermediate Docker