Inicio rápido de Apache Kafka: instalar Kafka 4.2 con CLI y ejemplos locales

Apache Kafka 4.2.0 es la versión actual admitida y es la mejor base para una implementación rápida moderna, ya que Kafka 4.x carece completamente de ZooKeeper y se basa en KRaft de forma predeterminada.

Esta guía es una implementación rápida práctica orientada a la línea de comandos: instalación de Kafka, inicio de un broker local, aprendizaje de las herramientas esenciales de la CLI de Kafka y finalización con dos ejemplos de extremo a extremo que puedes copiar en tu terminal.

Qué es Apache Kafka y para qué se utiliza

Apache Kafka es una plataforma de transmisión de eventos. En términos prácticos, la transmisión de eventos significa capturar datos de eventos en tiempo real desde fuentes (bases de datos, sensores, aplicaciones), almacenar las resultantes transmisiones de forma durable y procesarlos o enrutarlos en tiempo real (o más tarde).

Kafka reúne tres capacidades principales en una sola plataforma: publicar y suscribirse a flujos de eventos, almacenar flujos de forma durable 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 transmisión.

Para el 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 PostgreSQL, optimización de Elasticsearch y capas de datos nativas de IA.

Si estás desarrollando en AWS y necesitas una alternativa administrada, Construcción de microservicios impulsados por eventos con AWS Kinesis cubre la implementación de microservicios impulsados por eventos con Kinesis Data Streams.

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

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:

• Temas (Topics) organizan los eventos. Un tema es multi-productor y multi-suscriptor, y los eventos pueden leerse varias veces porque los controles de retención determinan cuándo se descarta los datos antiguos.
• Particiones fragmentan un tema entre brokers para escalabilidad; el orden se garantiza por partición.
• Factor de replicación controla la tolerancia a fallos. Los ejemplos de la 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 utiliza típicamente 1).

Instalación de 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 el desarrollo local.

Requisitos previos 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 de Java 8.

Si estás instalando Kafka específicamente para aprenderlo, apunta a una JDK admitida como Java 17 o 21. La página de soporte de Java de Kafka enumera Java 17, 21 y 25 como completamente admitidos, mientras que Java 11 se admite solo 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 de 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 de Apache y las KEYS.

Instalación con Docker

Kafka también proporciona imágenes oficiales de Docker en Docker Hub. La implementación rápida muestra que puedes extraer y ejecutar Kafka 4.2.0 así:

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 imágenes nativas 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 y destinada al desarrollo local y pruebas, no a 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 señala históricamente que en Windows debes usar bin\windows\ y scripts .bat en lugar de los scripts Unix bin/ .sh.

Iniciar Kafka localmente con KRaft

Si te preguntas “¿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 el 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 archivo comprimido extraído

La implementación rápida 4.2 de Kafka 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 “formato” en KRaft: La documentación de operaciones 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 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 esta implementación rápida

Para el desarrollo local, Kafka puede ejecutarse en una configuración simplificada “combinada” (controladores y brokers juntos). La documentación 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 quieres controladores aislados y escalables de forma independiente).

Para clústeres “reales”, los controladores y brokers 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é activa).

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 importante para Kafka 4.x: Los comandos de AdminClient ya no aceptan --zookeeper. La documentación de compatibilidad de Kafka señala que, a partir de 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 temas, grupos de consumidores y la mayoría de los comandos orientados al broker. Es el reemplazo canónico para los flujos de trabajo administrativos 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 administrativas usan puntos finales de broker. La página de operaciones KRaft muestra ambos estilos en ejemplos.

Gestión de temas con kafka-topics.sh

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

• Crear, describir y listar temas (la implementación rápida muestra --create, --describe, --topic).
• Especificar escala y 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.
• Agregar 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 producción” se ve así (esta forma exacta se utiliza 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 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 formateador) en favor de --formatter-property.
• kafka-console-producer deprecia --property (propiedades del lector de mensajes) en favor de --reader-property.

Si mantienes manuales de procedimientos internos, estas notas valen la pena actualizar ahora, antes de que Kafka 5.0 elimine las banderas obsoletas.

Inspección del 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 advertencia de configuración para Docker local y clientes remotos

Si ejecutas Kafka en contenedores o detrás de equilibradores de carga, eventualmente tendrás que configurar los receptores 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, especialmente cuando la dirección de enlace no es la dirección que los clientes deberían usar.

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

Los ejemplos a continuación están deliberadamente basados en la CLI para que puedas 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.

Abre la terminal A y crea un tema:

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 inicia 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:

Este es mi primer evento
Este es mi segundo evento

Abre la terminal C e inicia 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”: La implementación rápida de Kafka explica que los brokers almacenan eventos de forma durable 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 debes hacer después de cualquier instalación o actualización.

Ejemplo: ejecutar un pipeline simple de Kafka Connect de 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 descripción general de Kafka Connect lo describe como una herramienta para transmisión escalable y fiable entre Kafka y otros sistemas, mediante conectores.

La implementación rápida de Kafka 4.2 incluye una demostración mínima de Connect local utilizando 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 minúsculo:

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

• El conector de origen lee líneas de test.txt y las produce en el tema 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 tema directamente:

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

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

Solución de problemas y siguientes pasos

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

El broker falla al iniciar

Comienza con los requisitos oficiales:

• La implementación rápida de Kafka 4.2 requiere explícitamente Java 17+. Si tienes una JDK anterior, corrige eso primero.
• En el modo KRaft, el formateo de almacenamiento es un paso explícito obligatorio. Si omites kafka-storage.sh format, es probable que veas fallos de inicio o errores de metadatos.

Si experimentaste y ahora quieres 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, 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 a partir de Kafka 4.0.

Sorpresas de red de Docker

Si Kafka está en Docker y tu herramienta de cliente está fuera de Docker (o en otra máquina), es posible que necesites una publicidad de receptores correcta. La documentación de configuración del broker explica que advertised.listeners se utiliza 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 has completado los ejemplos de esta publicación, ya has respondido las búsquedas iniciales más comunes:

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

A partir de aquí, los siguientes pasos más valiosos suelen ser:

• Leer la “Introducción” de Kafka para modelos mentales más profundos de temas, particiones y replicación.
• Explorar la implementación rápida de Kafka Streams si quieres 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).