API HTTP y dashboard de Keeper

Documentación de la API HTTP de ClickHouse Keeper y del dashboard web integrado

ClickHouse Keeper proporciona una API HTTP y un dashboard web integrado para monitorización, comprobaciones de estado y gestión del almacenamiento. Esta interfaz permite a los operadores inspeccionar el estado del cluster, ejecutar comandos y gestionar el almacenamiento de Keeper desde un navegador web o mediante clientes HTTP.

​

Configuración

Para habilitar la API HTTP, añade la sección http_control a la configuración de keeper_server:

<keeper_server>
    <!-- Otra configuración de keeper_server -->

    <http_control>
        <port>9182</port>
        <!-- <secure_port>9443</secure_port> -->
    </http_control>
</keeper_server>

​

Opciones de configuración

Ajuste	Predeterminado	Descripción
http_control.port	-	Puerto HTTP para el dashboard y la API
http_control.secure_port	-	Puerto HTTPS (requiere configuración de SSL)
http_control.readiness.endpoint	/ready	Ruta personalizada para la sonda de disponibilidad
http_control.storage.session_timeout_ms	30000	Tiempo de espera de la sesión para operaciones de la API de almacenamiento

​

Endpoints

​

Dashboard

• Ruta: /dashboard
• Método: GET
• Descripción: Sirve un dashboard web integrado para monitorizar y gestionar Keeper

El dashboard proporciona:

• Visualización en tiempo real del estado del cluster
• Monitorización de nodos (rol, latencia, conexiones)
• Navegador de almacenamiento
• Interfaz para ejecutar comandos

​

Pestaña Cluster

La pestaña Cluster muestra los miembros de Raft como un grafo de topología y una tabla. Cada miembro se muestra con un color que indica su estado:

• Verde — activo y sincronizado con el líder
• Amarillo — activo, pero con un retraso de más de stale_log_gap entradas de registro respecto al líder
• Rojo — inaccesible (sin ninguna respuesta correcta de Raft dentro del intervalo de expiración del latido)
• Gris — desconocido (el estado de los pares solo es visible desde el líder; los seguidores ven el estado de sus pares como desconocido)

La tabla también muestra el rol de cada miembro (líder, seguidor u observador), la prioridad de Raft, el índice del último registro, el retraso de replicación respecto al líder y el tiempo transcurrido desde la última respuesta correcta de Raft. Cuando el nodo actual no es el líder, la pestaña ofrece un enlace directo que abre el dashboard del líder, donde está disponible el estado completo de los pares. La pestaña se puede abrir directamente con /dashboard?tab=cluster.

​

Sonda de disponibilidad

• Ruta: /ready (configurable)
• Método: GET
• Descripción: endpoint de comprobación de estado

Respuesta exitosa (HTTP 200):

{
  "status": "ok",
  "details": {
    "role": "leader",
    "hasLeader": true
  }
}

​

API de comandos

• Ruta: /api/v1/commands/{command}
• Métodos: GET, POST
• Descripción: Ejecuta comandos Four-Letter Word o comandos de la CLI de ClickHouse Keeper Client

Parámetros de consulta:

• command - El comando que se va a ejecutar
• cwd - Directorio de trabajo actual para comandos basados en rutas (predeterminado: /)

Ejemplos:

# Comando de cuatro letras
curl http://localhost:9182/api/v1/commands/stat

# Comando CLI de ZooKeeper
curl "http://localhost:9182/api/v1/commands/ls?command=ls%20'/'&cwd=/"

​

API de almacenamiento

• Ruta base: /api/v1/storage
• Descripción: API REST para operaciones de almacenamiento en Keeper

La API de almacenamiento sigue las convenciones REST, donde los métodos HTTP indican el tipo de operación:

Operación	Ruta	Método	Código de estado	Descripción
Obtener	/api/v1/storage/{path}	GET	200	Obtener datos del nodo
Listar	/api/v1/storage/{path}?children=true	GET	200	Listar nodos hijos
Existe	/api/v1/storage/{path}	HEAD	200	Comprobar si el nodo existe
Crear	/api/v1/storage/{path}	POST	201	Crear un nodo nuevo
Actualizar	/api/v1/storage/{path}?version={v}	PUT	200	Actualizar los datos del nodo
Eliminar	/api/v1/storage/{path}?version={v}	DELETE	204	Eliminar el nodo