Inicio rápido de Apache Kafka: instalación de Kafka 4.2 con CLI y ejemplos locales

Apache Kafka 4.2.0 es la línea de versiones soportada actualmente y constituye la mejor base para una implementación rápida moderna, ya que Kafka 4.x está completamente libre de ZooKeeper y se construye alrededor de KRaft por defecto.

Esta guía es una implementación rápida práctica y orientada a la línea de comandos: instalar Kafka, iniciar un broker local, aprender las herramientas esenciales de CLI de Kafka y finalizar con dos ejemplos de extremo a extremo que puede copiar y pegar en su terminal.

Qué es Apache Kafka y para qué se utiliza

Apache Kafka es una plataforma de streaming de eventos. En términos prácticos, el streaming de eventos significa capturar datos de eventos en tiempo real desde fuentes (bases de datos, sensores, aplicaciones), almacenar los flujos resultantes de manera duradera y procesarlos o enrutarlos en tiempo real (o más tarde).

Kafka reúne tres capacidades fundamentales en una sola plataforma: publicar y suscribirse a flujos de eventos, almacenar flujos de manera duradera durante el tiempo necesario y procesar flujos a medida que ocurren o de forma retrospectiva. Esa combinación es la razón por la que Kafka se utiliza para pipelines de datos en tiempo real, integración, mensajería y análisis de streaming.

Para obtener contexto sobre dónde encaja Kafka dentro de una infraestructura de datos más amplia, consulte el pilar Infraestructura de datos para sistemas de IA: Almacenamiento de objetos, bases de datos, búsqueda y arquitectura de datos de IA, que cubre almacenamiento de objetos compatible con S3, arquitectura de PostgreSQL, optimización de Elasticsearch y capas de datos nativas para IA.

Si está construyendo sobre AWS y necesita una alternativa gestionada, Construcción de microservicios orientados a eventos con AWS Kinesis cubre la implementación de microservicios impulsados por eventos con Kinesis Data Streams.

Operativamente, Kafka es un sistema distribuido de servidores y clientes que se comunican a través de un protocolo TCP de alto rendimiento: los brokers almacenan y sirven datos; los clientes (productores y consumidores) escriben y leen eventos, a menudo a gran escala y con tolerancia a fallos.

Algunos conceptos que verá repetidamente en la CLI:

• Temas (Topics) organizan los eventos. Un tema es multiproductor y multisuscriptor, y los eventos pueden leerse múltiples veces porque la retención controla cuándo se descarta los datos antiguos.
• Particiones fragmentan un tema a través de brokers para escalabilidad; el orden está garantizado por partición.
• Factor de replicación controla la tolerancia a fallos. Los ejemplos de documentación recomiendan comúnmente factores de replicación de 2 o 3 en producción (una implementación rápida de desarrollo de un solo nodo típicamente usa 1).

Instalar Apache Kafka

La implementación rápida oficial de Kafka utiliza la versión binaria (tarball) o la imagen oficial de Docker. Ambas son válidas para desarrollo local.

Requisitos previos que no debe omitir

Kafka 4.x requiere Java moderno: para el servidor y las herramientas, Java 17+ es la base para la ejecución local, y Kafka 4.0 eliminó el soporte para Java 8.

Si está instalando Kafka específicamente para aprenderlo, apunte a un JDK soportado como Java 17 o 21. La página de soporte de Java de Kafka enumera Java 17, 21 y 25 como completamente soportados, mientras que Java 11 solo se soporta para un subconjunto de módulos (clientes y streams).

Instalación desde la versión binaria oficial

La implementación rápida oficial para Kafka 4.2.0 comienza descargando y extrayendo la distribución binaria:

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

Notas para lectores avanzados:

• El “2.13” en el nombre del archivo refleja la línea de compilación de Scala. Para los binarios de Kafka 4.x, Scala 2.13 es la línea de distribución principal, y Kafka 4.0 eliminó el soporte para Scala 2.12.
• Si le preocupa la integridad de la cadena de suministro, la página de descargas documenta explícitamente que puede verificar las descargas utilizando los procedimientos y KEYS publicados por Apache.

Instalación con Docker

Kafka también proporciona imágenes oficiales de Docker en Docker Hub. La implementación rápida muestra que puede extraer y ejecutar Kafka 4.2.0 de la siguiente manera:

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

También existe una línea de imágenes “nativas” (basadas en imágenes nativas de GraalVM). La documentación de Kafka y la Propuesta de Mejora de Kafka (KIP) para esta línea de imágenes la describen como experimental e intended para desarrollo local y pruebas, no para producción.

Nota de plataforma para usuarios de Windows

Las distribuciones de Kafka incluyen scripts de Windows (archivos por lotes). La documentación de Kafka indica históricamente que en Windows debe usar bin\windows\ y scripts .bat en lugar de los scripts .sh de Unix bin/.

Iniciar Kafka localmente con KRaft

Si se pregunta “¿Necesito ZooKeeper para ejecutar Apache Kafka?”, la respuesta moderna es no. Kafka 4.0 es el primer lanzamiento mayor diseñado para operar completamente sin ZooKeeper, ejecutándose en modo KRaft por defecto, lo que reduce la sobrecarga operativa para el uso local y en producción.

Iniciar un broker local de un solo nodo desde el tarball extraído

La implementación rápida de Kafka 4.2 utiliza tres comandos:

1. Generar un UUID de clúster
2. Formatear los directorios de registro
3. Iniciar el servidor

# Generar un UUID de clúster
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Formatear directorios de registro (formato local independiente)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

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

¿Por qué importa el paso de “formateo” en KRaft: la documentación de operaciones de KRaft de Kafka explica que kafka-storage.sh random-uuid genera el ID del clúster y que cada servidor debe formatearse con kafka-storage.sh format. Una de las razones dadas es que el autoformateo puede ocultar errores, especialmente alrededor del registro de metadatos, por lo que se prefiere el formateo explícito.

Qué está ejecutando en esta implementación rápida

Para desarrollo local, Kafka puede ejecutarse en una configuración simplificada “combinada” (controladores y brokers juntos). La documentación de KRaft de Kafka señala que los servidores combinados son más simples para el desarrollo, pero no se recomiendan para entornos de implementación críticos (donde desea que los controladores estén aislados y escalables de forma independiente).

Para clústeres “reales”, los controladores y brokers de KRaft son roles separados (process.roles), y los controladores se implementan típicamente como un quórum de 3 o 5 nodos (la disponibilidad depende de que la mayoría esté viva).

Esenciales de CLI de Kafka y parámetros principales de línea de comandos

Kafka viene con muchas herramientas de CLI bajo bin/. La documentación oficial de operaciones enfatiza dos propiedades útiles:

• Las herramientas comunes viven en el directorio bin/ de la distribución.
• Cada herramienta imprime su uso completo de línea de comandos cuando se ejecuta sin argumentos.

También importante para Kafka 4.x: Los comandos AdminClient ya no aceptan --zookeeper. La documentación de compatibilidad de Kafka indica que, a partir de Kafka 4.0, debe usar --bootstrap-server para interactuar con el clúster.

Banderas de conexión de Kafka que usará constantemente

La mayoría de las herramientas necesitan un punto de entrada al clúster:

• --bootstrap-server host:port
  Úselo para operaciones de temas, grupos de consumidores y la mayoría de los comandos orientados al broker. Es el reemplazo canónico para los flujos de trabajo de administración basados en ZooKeeper en Kafka 4.x.

KRaft introduce puntos finales de broker vs controlador para algunas herramientas. Por ejemplo, kafka-features.sh y partes de las herramientas de metadatos pueden usar puntos finales de controlador, mientras que muchas operaciones de administración usan puntos finales de broker. La página de operaciones de KRaft muestra ambos estilos en ejemplos.

Gestión de temas con kafka-topics.sh

Usará kafka-topics.sh para el ciclo de vida central:

• Crear, describir y listar temas (la implementación rápida muestra --create, --describe, --topic).
• Especifique la escala y la durabilidad mediante particiones y factor de replicación. La guía de operaciones muestra --partitions y --replication-factor y explica cómo afectan a la escalabilidad y la tolerancia a fallos.
• Agregue sobrescrituras por tema en el momento de la creación con --config key=value (la documentación de configuración de temas muestra ejemplos concretos).

Un comando de creación “orientado a la producción” se ve así (esta forma exacta se usa en la documentación oficial de operaciones):

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

Producción y consumo con clientes de consola

La implementación rápida utiliza el productor y el consumidor de consola porque son rápidos para validación y pruebas de humo:

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

Kafka 4.2 también incluye mejoras de consistencia de CLI. En las notas de actualización:

• kafka-console-producer deprecia --max-partition-memory-bytes y recomienda --batch-size en su lugar.
• kafka-console-consumer deprecia --property (propiedades del formato) en favor de --formatter-property.
• kafka-console-producer deprecia --property (propiedades del lector de mensajes) en favor de --reader-property.

Si mantiene manuales de procedimientos internos, estas notas merecen una actualización ahora, antes de que Kafka 5.0 elimine las banderas obsoletas.

Inspeccionar el retraso del consumidor con kafka-consumer-groups.sh

Para sistemas reales, “¿Mi consumidor está al día?” es una pregunta diaria. La guía de operaciones demuestra:

• Listar grupos: --list
• Describir un grupo con desplazamientos y retrasos: --describe --group ...
• Describir miembros y asignaciones: --members y --verbose
• Eliminar grupos: --delete
• Restablecer desplazamientos de forma segura: --reset-offsets

Ejemplo:

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

Una salvedad de configuración para Docker local y clientes remotos

Si ejecuta Kafka en contenedores o detrás de balanceadores de carga, eventualmente chocará con la necesidad de configurar los escuchadores correctamente. La documentación de configuración del broker de Kafka explica advertised.listeners como las direcciones que los brokers anuncian a los clientes y otros brokers, particularmente cuando la dirección de enlace no es la dirección que los clientes deberían usar.

Ejemplos de implementación rápida que puede ejecutar ahora

Los ejemplos a continuación son deliberadamente basados en CLI para que pueda validar una configuración local de Kafka antes de escribir cualquier código de aplicación.

Ejemplo: ejecutar un tema y transmitir mensajes de extremo a extremo

Este es el flujo canónico “crear, producir, consumir” de la implementación rápida de Kafka 4.2.

Abra la terminal A y cree un tema:

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

Ahora descríbalos (opcional pero útil cuando está aprendiendo sobre particiones y factor de replicación):

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

Abra la terminal B e inicie un productor:

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

Escriba un par de líneas (cada línea se convierte en un evento), luego deje que el productor se ejecute:

This is my first event
This is my second event

Abra la terminal C e inicie un consumidor desde el principio:

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

Debería ver las mismas líneas impresas.

¿Por qué esto valida más que “funciona”: la implementación rápida de Kafka explica que los brokers almacenan eventos de manera duradera y que los eventos pueden leerse múltiples veces y por múltiples consumidores. Esa durabilidad es la razón por la que este patrón de implementación rápida es lo primero que debe hacer después de cualquier instalación o actualización.

Ejemplo: ejecutar un pipeline simple de Kafka Connect desde archivo a tema a archivo

Kafka Connect responde a la pregunta recurrente “¿Cómo muevo datos hacia y fuera de Kafka sin escribir productores y consumidores personalizados para todo”. La visión general de Kafka Connect lo describe como una herramienta para streaming escalable y confiable entre Kafka y otros sistemas, mediante conectores.

La implementación rápida de Kafka 4.2 incluye una demostración mínima y local de Connect utilizando los conectores de origen y destino de archivos.

Desde su directorio de Kafka, primero establezca la ruta del plugin del trabajador para incluir el jar del conector de archivos proporcionado:

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

Cree un archivo de entrada pequeño:

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

Inicie el trabajador de Connect en modo independiente con una configuración de conector de origen y destino:

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

Qué debería suceder (y por qué es útil):

• El conector de origen lee líneas de test.txt y las produce al tema connect-test.
• El conector de destino lee de connect-test y escribe en test.sink.txt.

Verifique el archivo de destino:

more test.sink.txt

Debería ver:

foo
bar

También puede verificar el tema directamente:

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

Este segundo ejemplo es un gran constructor de memoria muscular porque también le enseña dónde reside la configuración de Connect (configuración del trabajador más configuraciones de conector) y muestra un bucle mínimo de “ingesta, almacenamiento, exportación”.

Solución de problemas y siguientes pasos

La mayoría de los problemas de “Kafka Quickstart no inicia” se reducen a un pequeño conjunto de causas raíz.

El broker falla al iniciar

Comience con los requisitos oficiales:

• La implementación rápida de Kafka 4.2 requiere explícitamente Java 17+. Si está en un JDK más antiguo, corrija eso primero.
• En modo KRaft, el formateo de almacenamiento es un paso explícito obligatorio. Si omite kafka-storage.sh format, es probable que vea fallos de inicio o errores de metadatos.

Si experimentó y ahora desea empezar de cero, la implementación rápida de Kafka muestra cómo eliminar los directorios de datos locales utilizados en la demostración:

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

Los comandos de CLI fallan aunque el broker esté ejecutándose

En Kafka 4.x, valide que está usando --bootstrap-server (no --zookeeper). La documentación de compatibilidad de Kafka señala explícitamente la eliminación de --zookeeper de los comandos AdminClient a partir de Kafka 4.0.

Sorpresas de red de Docker

Si Kafka está en Docker y su herramienta de cliente está fuera de Docker (o en otra máquina), es posible que necesite una publicidad de escuchadores correcta. La documentación de configuración del broker explica que advertised.listeners se usa cuando las direcciones a las que los clientes deben conectarse difieren de las direcciones de enlace (listeners).

Dónde ir después de la implementación rápida

Si ha completado los ejemplos de este artículo, ya ha respondido las búsquedas iniciales más comunes:

• para qué se usa Kafka (streaming de eventos de extremo a extremo)
• cómo instalar Kafka localmente (tarball o Docker)
• por qué ZooKeeper ha desaparecido y KRaft es el defecto en 4.x
• qué herramientas de CLI importan día a día (temas, productor, consumidor, grupos)

Desde aquí, los siguientes pasos más valiosos suelen ser:

• Lea la “Introducción” de Kafka para modelos mentales más profundos de temas, particiones y replicación.
• Explore la implementación rápida de Kafka Streams si desea una primera aplicación de procesamiento (la implementación rápida de Streams demuestra ejecutar la demostración WordCount e inspeccionar resultados con el consumidor de consola).