Cómo crear y gestionar temas de Kafka utilizando la línea de comandos

Cómo crear y administrar temas de Kafka usando la línea de comandos

Apache Kafka es una plataforma distribuida de transmisión de eventos utilizada a menudo para canalizaciones de datos de alto rendimiento, análisis en tiempo real y comunicación entre microservicios. La unidad organizativa fundamental dentro de Kafka es el Tema (Topic), una categoría o nombre de feed al que se publican los registros.

Aunque existen herramientas gráficas, la forma más robusta, confiable y común de interactuar y administrar la infraestructura de Kafka es directamente a través de la interfaz de línea de comandos (CLI). Dominar estos comandos esenciales es crucial para los administradores y desarrolladores responsables de mantener un clúster de Kafka saludable y eficiente. Esta guía proporciona un tutorial paso a paso sobre el uso del script kafka-topics.sh para realizar las tareas de administración de temas más comunes.

Prerrequisitos y configuración

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

Todos los comandos requieren la dirección de al menos un broker de Kafka, especificada mediante la bandera --bootstrap-server. Si está utilizando una versión anterior de Kafka (anterior a la 2.2), es posible que todavía dependa de la bandera --zookeeper, pero --bootstrap-server es el estándar moderno y recomendado.

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

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

1. Creación de 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 ordenación 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: Creación de `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 todo el clúster).

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

Sugerencia: En un entorno de producción con N brokers, a menudo se recomienda un factor de replicación de 3 para alta disponibilidad (lo que permite la pérdida de dos brokers antes de que ocurra la pérdida de datos), y el número de particiones debe ajustarse en función del rendimiento previsto y las necesidades de paralelismo del consumidor.

2. Listar todos los temas

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

Ejemplo de comando

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

Ejemplo de salida:

sales-data
logistics-stream
__consumer_offsets

3. Descripción de 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 solución de problemas y la verificación. Utilice la bandera --describe.

Ejemplo de comando: Descripción de `sales-data`

kafka-topics.sh --describe --topic sales-data \n  --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 responsable actualmente 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): El subconjunto de réplicas que están completamente sincronizadas con el Líder. La alta disponibilidad requiere que el Líder esté en el ISR.

4. Modificación de temas existentes

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

A. Aumento de 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 (se aplica hash) los mensajes a las particiones. Si sus productores dependen de garantías de ordenación basadas en claves, aumentar las particiones puede romper la entrega ordenada para claves existentes.

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

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

B. Modificación de la configuración específica del tema

Puede anular la configuración global del broker (como el tiempo de retención de mensajes o las políticas de limpieza) para temas individuales utilizando la bandera --config.

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

kafka-topics.sh --alter --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS \n  --config retention.ms=86400000

Para eliminar una anulación de configuración específica y volver a la configuración predeterminada del broker, utilice la bandera --delete-config:

kafka-topics.sh --alter --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS \n  --delete-config retention.ms

5. Eliminación de un tema de Kafka

Los temas que ya no están en uso deben eliminarse correctamente para recuperar espacio en disco y mantener la higiene del clúster.

Habilitación de la eliminación de temas

Por defecto, los brokers de Kafka pueden deshabilitar la eliminación de temas por seguridad. Antes de poder eliminar un tema, asegúrese de que la siguiente configuración esté habilitada en su archivo server.properties en todos los brokers:

delete.topic.enable=true

Ejemplo de comando: Eliminación de `old-stream`

Utilice 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 \n  --bootstrap-server $BROKER_ADDRESS

Salida de confirmación:

Deletion of topic old-stream initiated successfully.

Resumen de comandos de administración de temas

Acción	Bandera(s)	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 actuales.	`--topic my-topic`
Alterar (Particiones)	`--alter`	Aumentar el número de particiones.	`--partitions N` (N > conteo actual)
Alterar (Config)	`--alter --config`	Anular los valores predeterminados del broker para un tema específico.	`--config retention.ms=...`
Eliminar	`--delete`	Eliminar un tema permanentemente.	`--topic my-topic`

Conclusión y próximos pasos

La línea de comandos sigue siendo la interfaz más potente y flexible para administrar su clúster de Kafka. Al dominar la utilidad kafka-topics.sh, usted obtiene un control granular sobre los parámetros de creación de temas, las anulaciones de configuración y las acciones administrativas necesarias como la eliminación y la descripción.

Próximos pasos:

Practique estos comandos en un entorno de desarrollo o preparación (staging).
Explore las opciones de configuración avanzada utilizando el comando --describe para ver la lista completa de propiedades configurables (ej. cleanup.policy, max.message.bytes).
Aprenda los comandos CLI correspondientes para la prueba de productores y consumidores (kafka-console-producer.sh y kafka-console-consumer.sh).