Cómo Crear y Gestionar Temas de Kafka Usando la Línea de Comandos

Los temas de Apache Kafka son donde tus productores escriben registros y tus consumidores los leen. Si necesitas crear, inspeccionar, redimensionar o eliminar un tema desde un terminal, la herramienta principal es kafka-topics.sh.

Las herramientas gráficas son útiles, pero los comandos CLI siguen siendo la forma más rápida de verificar lo que el clúster está haciendo durante un incidente o despliegue. Esta guía muestra los comandos de temas que usarás con más frecuencia y señala los lugares donde Kafka puede sorprenderte.

Prerrequisitos y Configuración

Para ejecutar los comandos de esta guía, debes tener acceso a una máquina donde los binarios de Kafka estén instalados. Todas las operaciones de gestión de temas se realizan utilizando la utilidad kafka-topics.sh, que normalmente se encuentra en el directorio bin de tu instalación de Kafka.

Todos los comandos requieren la dirección de al menos un broker de Kafka, especificada con --bootstrap-server. Los clústeres de Kafka más antiguos pueden mostrar ejemplos usando --zookeeper, pero la administración basada en brokers es el patrón actual.

Para los ejemplos a continuación, asumiremos que el broker se ejecuta localmente en el puerto predeterminado:

# Marcador de posición de dirección de broker estándar
BROKER_ADDRESS="localhost:9092"

1. Crear un Nuevo Tema de Kafka

Crear un tema requiere definir su nombre, junto con dos parámetros críticos que dictan su comportamiento y tolerancia a fallos: el número de particiones y el factor de replicación.

Parámetros Esenciales

--topic <nombre>: El nombre del tema.
--partitions <N>: El número de particiones en las que se dividirá el tema. Las particiones son las unidades de paralelismo y orden dentro de un tema.
--replication-factor <N>: El número de copias de los datos que se mantendrán en diferentes brokers. Un factor de replicación de 1 significa que no hay redundancia.

Ejemplo de Comando: Crear `sales-data`

Este comando crea un tema llamado sales-data con 3 particiones y un factor de replicación de 2 (lo que significa que existirán 2 copias de cada partición en el clúster).

kafka-topics.sh --create --topic sales-data \
  --bootstrap-server $BROKER_ADDRESS \
  --partitions 3 \
  --replication-factor 2

Consejo: En producción, un factor de replicación de 3 es común porque mantiene múltiples copias de cada partición en diferentes brokers. La tolerancia a fallos real también depende de la ubicación del broker, min.insync.replicas y la configuración de acuse de recibo del productor.

2. Listar Todos los Temas

Para ver todos los temas disponibles actualmente en el clúster de Kafka, usa la bandera --list.

Ejemplo de Comando

kafka-topics.sh --list --bootstrap-server $BROKER_ADDRESS

Ejemplo de Salida:

sales-data
logistics-stream
__consumer_offsets

3. Describir la Configuración del Tema

Verificar la configuración existente, el recuento de particiones y la asignación de brokers para un tema específico es esencial para la resolución de problemas y la verificación. Usa la bandera --describe.

Ejemplo de Comando: Describir `sales-data`

kafka-topics.sh --describe --topic sales-data \
  --bootstrap-server $BROKER_ADDRESS

Interpretación de la Salida:

La salida muestra la configuración tanto a nivel de tema como a nivel de partición:

Topic: sales-data  PartitionCount: 3 ReplicationFactor: 2 Configs:
  Topic: sales-data  Partition: 0 Leader: 1 Replicas: 1,2 Isr: 1,2
  Topic: sales-data  Partition: 1 Leader: 2 Replicas: 2,0 Isr: 2,0
  Topic: sales-data  Partition: 2 Leader: 0 Replicas: 0,1 Isr: 0,1

Leader: El broker actualmente responsable de manejar lecturas/escrituras para esa partición.
Replicas: La lista de brokers que tienen una copia de esa partición.
Isr (In-Sync Replicas): Las réplicas que están suficientemente actualizadas para ser elegibles para una conmutación por error segura. Si ISR se reduce, verifica el estado del broker, la latencia del disco y la latencia de la red.

4. Modificar Temas Existentes

Kafka proporciona mecanismos limitados para modificar temas después de su creación. Las dos tareas de modificación más comunes son aumentar el recuento de particiones y anular la configuración predeterminada del broker.

A. Aumentar Particiones

Las particiones solo se pueden aumentar, nunca disminuir. Aumentar las particiones ayuda a escalar el paralelismo del consumidor.

Advertencia: Aumentar las particiones cambia cómo se asignan (hashean) los mensajes a las particiones. Si tus productores dependen de garantías de orden basadas en claves, aumentar las particiones puede romper la entrega ordenada para las claves existentes.

Si sales-data actualmente tiene 3 particiones, podemos aumentarlas a 5:

kafka-topics.sh --alter --topic sales-data \
  --bootstrap-server $BROKER_ADDRESS \
  --partitions 5

B. Modificar la Configuración Específica del Tema

Puedes ver ejemplos antiguos que cambian la configuración del tema a través de kafka-topics.sh --alter --config. En los clústeres de Kafka actuales, prefiere kafka-configs.sh para los cambios de configuración de temas porque es la herramienta de administración dedicada para configuraciones dinámicas.

Ejemplo: Establecer un tiempo de retención de mensajes de 24 horas (86400000 milisegundos) para sales-data.

kafka-configs.sh --bootstrap-server $BROKER_ADDRESS \
  --alter --entity-type topics --entity-name sales-data \
  --add-config retention.ms=86400000

Para eliminar una anulación de configuración específica y volver al valor predeterminado del broker, usa --delete-config:

kafka-configs.sh --bootstrap-server $BROKER_ADDRESS \
  --alter --entity-type topics --entity-name sales-data \
  --delete-config retention.ms

5. Eliminar un Tema de Kafka

Los temas que ya no se utilizan deben eliminarse adecuadamente para recuperar espacio en disco y mantener la higiene del clúster.

Habilitar la Eliminación de Temas

Los brokers de Kafka deben permitir la eliminación antes de que este comando pueda eliminar datos. En muchas implementaciones modernas está habilitado, pero no lo des por sentado. Verifica la configuración del broker para:

delete.topic.enable=true

Ejemplo de Comando: Eliminar `old-stream`

Usa la bandera --delete para iniciar la eliminación del tema. La eliminación de temas suele ser asíncrona, lo que significa que el comando envía la solicitud y la eliminación ocurre en segundo plano.

kafka-topics.sh --delete --topic old-stream \
  --bootstrap-server $BROKER_ADDRESS

Salida de Confirmación:

Deletion of topic old-stream initiated successfully.

Resumen de Comandos de Gestión de Temas

Acción	Banderas	Propósito	Parámetros de Ejemplo
Crear	`--create`	Inicializar un nuevo tema.	`--partitions 5 --replication-factor 3`
Listar	`--list`	Mostrar todos los temas en el clúster.	N/A
Describir	`--describe`	Ver la configuración y el diseño actual.	`--topic my-topic`
Modificar (Particiones)	`--alter`	Aumentar el número de particiones.	`--partitions N` (N > recuento actual)
Modificar (Config)	`kafka-configs.sh --alter`	Anular los valores predeterminados del broker para un tema específico.	`--add-config retention.ms=...`
Eliminar	`--delete`	Eliminar un tema permanentemente.	`--topic my-topic`

Próximos Pasos

Practica estos comandos en un entorno de desarrollo o pruebas.
Usa kafka-configs.sh --describe antes y después de los cambios de configuración para saber qué valores son anulaciones de temas.
Aprende los comandos CLI correspondientes para pruebas de productores y consumidores (kafka-console-producer.sh y kafka-console-consumer.sh).