Introducción a Apache Kafka: instalación de Kafka 4.2 con CLI y ejemplos locales

Apache Kafka 4.2.0 es la versión actual soportada y constituye la mejor base para una guía de inicio rápido moderna, ya que Kafka 4.x está completamente libre de ZooKeeper y se basa en KRaft de forma predeterminada.

Esta guía es un inicio rápido práctico, centrado en la línea de comandos: instalar Kafka, iniciar un broker local, aprender las herramientas esenciales de la CLI de Kafka y finalizar con dos ejemplos de extremo a extremo que puedes copiar y pegar en tu 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 las secuencias resultantes de manera duradera y procesarlas o enrutarlas en tiempo real (o posteriormente).

Kafka reúne tres capacidades principales en una sola plataforma: publicar y suscribirse a flujos de eventos, almacenar flujos de manera duradera durante todo el tiempo necesario y procesar flujos a medida que ocurren o retrospectivamente. Esta combinación es la razón por la que Kafka se utiliza para pipelines de datos en tiempo real, integración, mensajería y analítica de streaming.

Para tener contexto sobre dónde encaja Kafka dentro de una infraestructura de datos más amplia, consulta el pilar de Infraestructura de Datos para Sistemas de IA: Almacenamiento de Objetos, Bases de Datos, Búsqueda y Arquitectura de Datos para 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ás construyendo sobre AWS y necesitas una alternativa administrada, Construcción de Microservicios Orientados a Eventos con AWS Kinesis cubre la implementación de microservicios orientados a eventos con Kinesis Data Streams.

Para el procesamiento de flujos con estado usando Kafka, consulta Apache Flink en K8s y Kafka: PyFlink, Go, operaciones y precios administrados.

Para servicios que escriben en una base de datos antes de publicar en Kafka, el patrón de outbox transaccional asegura que los eventos nunca se pierdan entre el commit de la base de datos y la llamada de producción en Kafka.

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ás repetidamente en la CLI:

• Los Topics (temas) organizan los eventos. Un topic es multi-productor y multi-suscriptor, y los eventos pueden leerse múltiples veces porque la retención controla cuándo se descarta los datos antiguos.
• Las Particiones dividen un topic entre brokers para escalabilidad; el orden está garantizado por partición.
• El factor de replicación controla la tolerancia a fallos. La documentación de los ejemplos recomienda comúnmente factores de replicación de 2 o 3 en producción (un inicio rápido de desarrollo de nodo único típicamente usa 1).

Instalar Apache Kafka

El inicio rápido oficial de Kafka utiliza la versión binaria (tarball) o la imagen oficial de Docker. Ambas son válidas para el desarrollo local.

Prerrequisitos que no debes 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ás instalando Kafka específicamente para aprenderlo, apunta a un JDK soportado como Java 17 o 21. La página de soporte de Java de Kafka lista Java 17, 21 y 25 como completamente soportados, mientras que Java 11 es soportado solo para un subconjunto de módulos (clientes y streams).

Instalar desde la versión binaria oficial

El inicio rápido 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 construcció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 te preocupa la integridad de la cadena de suministro, la página de descargas documenta explícitamente que puedes verificar las descargas utilizando los procedimientos publicados por Apache y las KEYS.

Instalar con Docker

Kafka también proporciona imágenes oficiales de Docker en Docker Hub. El inicio rápido muestra que puedes obtener y ejecutar Kafka 4.2.0 de esta 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” (basada en imagen nativa de GraalVM). La documentación de Kafka y la Propuesta de Mejora de Kafka para esta línea de imágenes la describen como experimental e intencionada para desarrollo local y pruebas, no para producción.

Nota de plataforma para usuarios de Windows

Las distribuciones de Kafka incluyen scripts para Windows (archivos batch). La documentación de Kafka nota históricamente que en Windows debes usar bin\windows\ y scripts .bat en lugar de los scripts .sh de Unix en bin/.

Iniciar Kafka localmente con KRaft

Si te preguntas “¿Necesito ZooKeeper para ejecutar Apache Kafka”, la respuesta moderna es no. Kafka 4.0 es la primera versión principal diseñada para operar completamente sin ZooKeeper, ejecutándose en modo KRaft de forma predeterminada, lo que reduce la sobrecarga operativa para uso local y en producción.

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

El inicio rápido de Kafka 4.2 utiliza tres comandos:

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

# Generar un UUID del 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é el paso de “formato” es importante 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 ser formateado con kafka-storage.sh format. Una razón dada es que el formateo automático puede ocultar errores, especialmente alrededor del registro de metadatos, por lo que se prefiere el formateo explícito.

Qué estás ejecutando en este inicio rápido

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

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

Esenciales de la 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 se encuentran 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 es importante para Kafka 4.x: Los comandos de AdminClient ya no aceptan --zookeeper. La documentación de compatibilidad de Kafka nota que, comenzando con Kafka 4.0, debes usar --bootstrap-server para interactuar con el clúster.

Banderas de conexión de Kafka que usarás constantemente

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

• --bootstrap-server host:port
  Usa esto para operaciones de topics, grupos de consumidores y la mayoría de los comandos dirigidos al broker. Es el reemplazo canónico para 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 los ejemplos.

Gestión de topics con kafka-topics.sh

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

• Crear, describir, listar topics (el inicio rápido muestra --create, --describe, --topic).
• Especificar escala y durabilidad a través de particiones y factor de replicación. La guía de operaciones muestra --partitions y --replication-factor y explica cómo afectan la escalabilidad y la tolerancia a fallos.
• Agregar sobrescrituras por topic en el momento de la creación con --config key=value (la documentación de configuración de topics muestra ejemplos concretos).

Un buen comando de creación “orientado a 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

Producir y consumir con clientes de consola

El inicio rápido usa el productor y 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 en la CLI. En las notas de actualización:

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

Si mantienes libros de ejecución internos, estas notas merecen ser actualizadas ahora, antes de que Kafka 5.0 elimine las banderas deprecadas.

Inspeccionar el retraso de consumidores 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 offsets y retraso: --describe --group ...
• Describir miembros y asignaciones: --members y --verbose
• Eliminar grupos: --delete
• Restablecer offsets de manera segura: --reset-offsets

Ejemplo:

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

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

Si ejecutas Kafka en contenedores o detrás de equilibradores de carga, eventualmente te encontrarás con la necesidad de configurar los listeners 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 vinculación no es la dirección que los clientes deberían usar.

Ejemplos de inicio rápido que puedes ejecutar ahora

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

Ejemplo ejecutar un topic y transmitir mensajes de extremo a extremo

Este es el flujo canónico “crear, producir, consumir” del inicio rápido de Kafka 4.2.

Abre la terminal A y crea un topic:

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

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

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

Abre la terminal B y comienza un productor:

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

Escribe un par de líneas (cada línea se convierte en un evento), luego deja el productor ejecutándose:

This is my first event
This is my second event

Abre la terminal C y comienza un consumidor desde el principio:

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

Deberías ver las mismas líneas impresas.

Por qué esto valida más que “funciona”: El inicio rápido 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 inicio rápido es lo primero que deberías hacer después de cualquier instalación o actualización.

Ejemplo ejecutar una pipeline simple de Kafka Connect de archivo a topic a archivo

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

El inicio rápido de Kafka 4.2 incluye una demostración local mínima de Connect usando los conectores de origen y destino de archivo.

Desde tu directorio de Kafka, primero establece la ruta del plugin del trabajador para incluir el jar del conector de archivo proporcionado:

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

Crea un archivo de entrada pequeño:

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

Inicia 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 pasar (y por qué es útil):

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

Verifica el archivo de destino:

more test.sink.txt

Deberías ver:

foo
bar

También puedes verificar el topic 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 te enseña dónde se encuentra la configuración de Connect (configuración del trabajador más configuraciones de conectores) y muestra un ciclo mínimo de “ingresar, almacenar, exportar”.

Solución de problemas y próximos pasos

La mayoría de los problemas de “el inicio rápido de Kafka no inicia” caen en un pequeño conjunto de causas raíz.

El broker falla al iniciar

Comienza con los requisitos oficiales:

• El inicio rápido de Kafka 4.2 requiere explícitamente Java 17+. Si estás en un JDK más antiguo, corrige eso primero.
• En modo KRaft, formatear el almacenamiento es un paso explícito requerido. Si omites kafka-storage.sh format, es probable que veas fallos de inicio o errores de metadatos.

Si experimentaste y ahora quieres una hoja en blanco, el inicio rápido 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 la CLI fallan aunque el broker esté ejecutándose

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

Sorpresas de networking en Docker

Si Kafka está en Docker y tu herramienta de cliente está fuera de Docker (o en otra máquina), puede que necesites la publicidad de listeners 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 vinculación (listeners).

Dónde ir después del inicio rápido

Si has completado los ejemplos en este artículo, ya has 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 desapareció y KRaft es el predeterminado en 4.x
• qué herramientas de la CLI importan día a día (topics, productor, consumidor, grupos)

Desde aquí, los próximos pasos más valiosos suelen ser:

• Leer la “Introducción” de Kafka para modelos mentales más profundos de topics, particiones y replicación.
• Explorar el Inicio Rápido de Kafka Streams si quieres una primera aplicación de procesamiento (el inicio rápido de Streams demuestra ejecutar la demostración de WordCount e inspeccionar resultados con el consumidor de consola).