Referencia de la API
Referencia de la API REST
Todas las rutas para usuarios bajo /api/v1: URLs base, autenticación, selección de clúster, roles, errores, simulaciones (dry run) y las tablas de endpoints.
En esta página
Todo lo que hace la interfaz pasa por esta API, así que cualquier cosa que
puedas hacer en KubeBolt la puedes automatizar con un script. Todas las rutas
están bajo /api/v1, con unas pocas excepciones montadas en la raíz: el
WebSocket de la terminal de pods en /ws/exec/{namespace}/{name}, el proxy
inverso de port-forward en /pf/{id}/, la sonda /health y el /metrics
propio de la API.
URL base
| Instalación | URL base |
|---|---|
| Chart de Helm o Docker Compose, a través de la URL de la interfaz | https://<your-kubebolt>/api/v1: el nginx incluido hace de proxy de /api/ hacia la API |
| Chart de Helm, desde dentro del clúster | http://<release>-api.<namespace>.svc:8080/api/v1 |
| Binario único / contenedor único | El puerto en el que sirve (8080 para el binario, 3000 en la imagen de contenedor), más /api/v1 |
| KubeBolt Cloud | https://api.kubebolt.io/api/v1 |
Autenticación
Envía Authorization: Bearer <token> en cada petición. El token es o bien un
token de acceso de sesión de POST /auth/login (15 minutos por defecto;
consulta Autenticación), o bien un
token de API (kbk_ / kbs_), que es lo que deberían
usar los scripts, CI y los hosts MCP. Se aplican el rol, los scopes y la lista
de clústeres del token de API.
Tokens de API y el edge público. Los tokens de servicio kbs_ se
rechazan cuando la petición llega a través del nginx incluido o de la ruta de
Gateway API del chart, que fuerzan X-KubeBolt-Edge: public. Desde fuera,
usa una clave de API kbk_; para llamadas de máquina a máquina, llega
directamente al Service de la API. Consulta
Tokens de API.
Con la autenticación activada, todo requiere un token salvo estas rutas públicas:
| Ruta | Por qué es pública |
|---|---|
GET /auth/config | La página de inicio de sesión necesita saber si la autenticación y el registro están activados (enabled, signupEnabled) |
POST /auth/login · POST /auth/refresh | Establecer y rotar la sesión |
POST /auth/signup | Registro de organizaciones en autoservicio. Devuelve 409 con "code": "requires_ee" en la edición open source |
GET /copilot/config | La página de inicio de sesión decide si muestra el panel de chat. Autenticación opcional: un token válido resuelve tu organización y uno inválido se ignora en lugar de rechazarse |
GET /config/ui | Nombre visible e intervalo de refresco por defecto: elementos de la interfaz, sin secretos |
POST /prom/write | Ingesta de remote-write. La controlan KUBEBOLT_REMOTE_WRITE_ENABLED (desactivada por defecto) y su propio modo de token de ingesta, no una sesión |
POST /ingest/falco | Eventos de runtime de Falco. Se autentica dentro del handler con un token de ingesta asociado al clúster: estricto, sin fallback permisivo |
En la raíz, GET /health responde ok sin autenticación, y una API
autoalojada sirve métricas de Prometheus sobre sí misma en GET /metrics, en
su propio puerto y también sin autenticación, así que mantén ese puerto fuera
del edge público. KubeBolt Cloud añade rutas públicas para el inicio de sesión
con cuentas sociales, la verificación del correo, el restablecimiento de
contraseña y las invitaciones; dan servicio a las páginas de inicio de sesión
y no están pensadas para scripts.
Seleccionar un clúster
Las rutas que leen o cambian un clúster actúan sobre el clúster indicado en la
cabecera X-KubeBolt-Cluster: su context de GET /clusters, por ejemplo
prod-eu-west, o agent: seguido del id del clúster para un clúster conectado
por agente. Sin la cabecera, actúan sobre el clúster seleccionado en ese
momento en KubeBolt. POST /clusters/switch cambia esa selección para todos
los usuarios de la instalación (en Cloud, para toda la organización), así que
la automatización debería enviar la cabecera en lugar de cambiar de clúster.
La columna En vivo de las tablas siguientes marca las rutas que necesitan
ese clúster conectado en este momento. Cuando no lo está, responden 503 con
el motivo: cluster not connected (o el error de conexión),
no cluster selected — choose a cluster to continue,
no agent connected yet for this cluster — waiting for agent to register o,
para un clúster solo de monitoreo,
cluster is monitored-only — …. Después de una conexión fallida, el motivo
termina en (next attempt in …): las peticiones esperan 30 segundos, luego 1,
2 y 4 minutos, 5 como máximo, en lugar de empezar cada una una conexión nueva;
un agente que se reconecta o POST /clusters/switch lo intentan en el acto.
Las rutas sin la marca leen datos almacenados (historial, hallazgos, el
almacén de métricas) y siguen respondiendo para clústeres caídos o que ya no
existen.
En las rutas de recursos, {ns} es el namespace; usa _ para los recursos de
ámbito de clúster, como los nodos. Codifica para URL {context} y el valor de
la cabecera: los contextos de EKS son ARNs con : y /.
Roles
Las lecturas necesitan cualquier rol autenticado, salvo el explorador de
archivos del pod: ejecuta comandos dentro del contenedor, así que necesita
Editor, como la terminal. Las escrituras necesitan Editor; las acciones destructivas (DELETE sobre un recurso, drenar un
nodo) y toda la superficie de administración necesitan Admin. Algunos
handlers suben todavía más el listón: revelar un Secret en un namespace con
patrón de producción necesita Admin. En KubeBolt Cloud, quienes tienen rol
Editor o Viewer solo llegan a los clústeres de sus equipos. Sea cual sea el
rol, el RBAC del propio clúster tiene la última palabra: consulta
RBAC.
Errores
Los errores llevan un cuerpo JSON con un mensaje error y, a veces, un code
legible por máquinas:
{ "error": "insufficient permissions" }
{ "error": "self-service signup requires the multi-org edition", "code": "requires_ee" }
| Estado | Significado |
|---|---|
400 | Cuerpo o parámetros mal formados |
401 | Falta el token, o está mal formado, caducado o revocado (authentication required, invalid or expired token) |
403 | El rol no alcanza (insufficient permissions); un token de API está fuera de sus scopes o en una ruta a la que ningún token puede llegar; el clúster no es uno que el cliente pueda leer (you do not have access to this cluster); el RBAC de Kubernetes denegó la lectura (insufficient permissions to access <type>); en Cloud, "code": "email_unverified" hasta que se verifica el correo |
404 | No existe ese recurso o esa ruta. En Cloud, la administración de toda la instalación responde 404 a los usuarios de las organizaciones |
409 | Conflicto, como un nombre de usuario que ya existe; "code": "requires_ee" para funciones exclusivas de Cloud en la edición open source |
429 | Inicio de sesión limitado (con Retry-After); un desalojo bloqueado por un PodDisruptionBudget |
502 | No se puede llegar a un servicio del que depende KubeBolt: el almacén de métricas, el proveedor de IA, un canal de notificaciones |
503 | El clúster no está en vivo (ver arriba), o el almacén que respalda la función está apagado (por ejemplo, con la autenticación desactivada) |
No hay un límite general de peticiones en la API REST. El inicio de sesión se limita por nombre de usuario (en Cloud, las rutas de inicio de sesión también por IP de cliente), y la ingesta de remote-write, por tenant.
Listas y paginación
GET /resources/{type} filtra y pagina en el servidor y devuelve
{kind, items, total}:
| Parámetro | Significado |
|---|---|
namespace | Un namespace; omítelo para todos |
search | Subcadena del nombre o del namespace |
status | Estado exacto, o degraded para todo lo que no está sano (pending, en crash loop, no listo) |
node | Pods de un nodo |
sort · order | Columna y asc / desc; por defecto ordena por nombre, así que las páginas son estables |
page · limit | Desde la página 1, 50 por página por defecto |
Acepta pods, deployments, statefulsets, daemonsets, replicasets,
jobs, cronjobs, services, endpoints, ingresses, networkpolicies,
gateways, httproutes, pdbs, hpas, configmaps, secrets,
serviceaccounts, pvcs, pvs, storageclasses, nodes, namespaces,
events, roles, clusterroles, rolebindings, clusterrolebindings, y
los CRDs opcionales certificates, argocdapps, vpas,
ciliumnetworkpolicies y ciliumclusterwidenetworkpolicies. Un tipo
desconocido devuelve una lista vacía.
En otras rutas: /findings pagina con page y pageSize (25 por defecto,
200 como máximo), /insights/episodes con page y limit (200 como máximo),
/events y /admin/actions aceptan un limit, y GET /insights devuelve la
lista completa.
Simulaciones (dry run)
Restart, scale, rollback, set-image, set-resources, set-env, set-bounds, debug
y delete aceptan ?dryRun=true. La petición pasa por toda la admisión del lado
del servidor (dryRun=All), es decir, validación, cuotas, LimitRanges y
webhooks, y no se persiste nada. La respuesta siempre es 200, con el
veredicto en el cuerpo:
{ "ok": false, "message": "ResourceQuota \"team-quota\" exceeded", "quota": { … } }
Consulta Acciones y gobernanza.
Ejemplos
Con una clave de API cuyos scopes cubran las rutas usadas:
KB=https://kubebolt.example.com/api/v1
AUTH="Authorization: Bearer $KUBEBOLT_TOKEN"
# Clústeres que el token puede leer (scope /api/v1/clusters)
curl -s -H "$AUTH" "$KB/clusters" | jq -r '.[] | "\(.context)\t\(.status)"'
# Pods con problemas en un namespace de un clúster (scope /api/v1/resources)
curl -s -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" \
"$KB/resources/pods?namespace=shop&status=degraded&limit=100"
# Las últimas 200 líneas del log de un contenedor
curl -s -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" \
"$KB/resources/pods/shop/checkout-7d9f8c6b5-x2x4q/logs?container=app&tailLines=200"
# Insights críticos (scope /api/v1/insights)
curl -s -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" "$KB/insights?severity=critical"
# Escalar un Deployment: primero la vista previa, después aplicar (rol Editor)
curl -s -X POST -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" \
-H 'Content-Type: application/json' -d '{"replicas": 3}' \
"$KB/resources/deployments/shop/checkout/scale?dryRun=true"
# Working set de memoria por namespace (scope /api/v1/metrics)
curl -s -G -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" "$KB/metrics/query" \
--data-urlencode 'query=sum by (namespace) (container_memory_working_set_bytes)'
Las opciones predefinidas de scopes del formulario no incluyen
/api/v1/clusters; añádelo al crear la clave por la API, o elige
Everything, si el script necesita listar clústeres.
Clústeres
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET | /clusters | Cualquiera | no | Clústeres registrados (contextos de kubeconfig, in-cluster, conectados por agente) con context, clusterId, status, mode y nombre visible, y agentUpdate cuando los agentes conectados del clúster van por detrás de la última versión: level (current, available, recommended), version (o before para un agente que no informa la suya), latest, reasons y el comando upgrade |
| GET | /clusters/names | Cualquiera | no | Nombres visibles de todos los clústeres, incluidos los dados de baja |
| POST | /clusters/switch | Cualquiera | no | Selecciona el clúster activo: {"context": "…"}. Lo comparten todos los usuarios de la instalación |
| GET | /clusters/progress | Cualquiera | no | Cuánto ha avanzado la conexión del clúster de la petición: su estado, los tipos de recurso sincronizados, los bytes recibidos y, tras un fallo, el error y cuándo será el siguiente intento. Nunca inicia una conexión ni la espera |
| POST | /clusters | Admin | no | Registra clústeres desde un kubeconfig: {"kubeconfig": "<yaml>"}, o el YAML tal cual con Content-Type: application/yaml |
| PUT | /clusters/{context}/rename | Admin | no | {"displayName": "…"}; un nombre vacío lo borra |
| DELETE | /clusters/{context} | Admin | no | Elimina un contexto de kubeconfig subido |
| DELETE | /clusters/by-id/{clusterId} | Admin | no | Elimina un clúster conectado por agente. Vuelve a aparecer si su agente sigue conectado |
| GET | /cluster/overview | Cualquiera | sí | Resumen del clúster: recuentos, CPU/memoria, salud, eventos, workloads. Los clústeres solo de monitoreo reciben un resumen basado en métricas |
| GET | /cluster/health | Cualquiera | sí | Detalle de la puntuación de salud |
| GET | /cluster/permissions | Cualquiera | sí | RBAC comprobado por tipo de recurso: consulta RBAC |
| GET | /coverage | Cualquiera | no | Qué fuentes de datos están enviando muestras para el clúster |
| GET | /update-check | Cualquiera | no | Última versión estable de KubeBolt en GitHub. {"enabled": false} cuando la comprobación está desactivada |
Recursos
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET | /resources/{type} | Cualquiera | sí | Lista filtrada y paginada: consulta Listas y paginación |
| GET | /resources/{type}/{ns}/{name} | Cualquiera | sí | Detalle; los pods y los nodos incluyen CPU y memoria en vivo |
| GET | /resources/{type}/{ns}/{name}/yaml | Cualquiera | sí | YAML (text/yaml): valores de los Secrets enmascarados, valores de ConfigMaps que parecen sensibles enmascarados, values de Helm, parámetros y entorno de plugin de una Application de Argo CD ocultos, managedFields eliminado |
| GET | /resources/{type}/{ns}/{name}/describe | Cualquiera | sí | Salida al estilo de kubectl describe, con los mismos valores ocultos que el YAML |
| GET | /resources/pods/{ns}/{name}/logs | Cualquiera | sí | Logs en texto plano: container, tailLines (100 si no se da un límite de tiempo), since (una duración), sinceTime / endTime (RFC 3339), previous, timestamps |
| GET | /resources/pods/{ns}/{name}/files · /files/content · /files/download | Editor | sí | Explorador de archivos del pod (container, path). Editor desde la 2.6.4, como la terminal. Las lecturas y las descargas se auditan |
| GET | /resources/{workload}/{ns}/{name}/pods | Cualquiera | sí | Pods de un Deployment, StatefulSet, DaemonSet o Job |
| GET | /resources/{type}/{ns}/{name}/history | Cualquiera | sí | Historial de revisiones (Deployments mediante ReplicaSets; StatefulSets/DaemonSets mediante ControllerRevisions) |
| GET | /resources/cronjobs/{ns}/{name}/jobs | Cualquiera | sí | Jobs hijos de un CronJob |
| GET | /topology | Cualquiera | sí | El grafo de relaciones del clúster: consulta Cluster Map |
| GET | /events | Cualquiera | sí | Eventos de Kubernetes: type, namespace, involvedKind, involvedName, limit (100 por defecto). 403 cuando las credenciales de KubeBolt no pueden listar eventos |
| GET | /search | Cualquiera | sí | Búsqueda por nombre en todos los tipos de recurso (q, hasta 50 resultados). scope=fleet busca en todos los clústeres que puedes leer y no necesita que el seleccionado esté en vivo, así que ⌘K sigue funcionando cuando un clúster está caído |
Acciones
Todas las acciones se auditan. La mayoría de los cuerpos son pequeños; los habituales están debajo de la tabla, y Acciones y gobernanza relaciona cada acción con las propuestas de Kobi.
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| PUT | /resources/{type}/{ns}/{name}/yaml | Editor | sí | Aplica el YAML editado (cuerpo en YAML tal cual) |
| POST | /resources/{type}/{ns} | Editor | sí | Crea un recurso a partir de un único manifiesto YAML o JSON |
| POST | /resources/{type}/{ns}/{name}/restart | Editor | sí | Reinicio progresivo (rolling restart) |
| POST | /resources/{type}/{ns}/{name}/scale | Editor | sí | Escala un Deployment o un StatefulSet |
| POST | /resources/{type}/{ns}/{name}/rollback | Editor | sí | Vuelve a una revisión anterior (rollback) |
| POST | /resources/{type}/{ns}/{name}/set-image | Editor | sí | Cambia las imágenes de los contenedores |
| POST | /resources/{type}/{ns}/{name}/set-resources | Editor | sí | Cambia requests/limits |
| POST | /resources/{type}/{ns}/{name}/set-env | Editor | sí | Define o elimina variables de entorno |
| POST | /resources/hpas/{ns}/{name}/set-bounds | Editor | sí | Réplicas mínimas/máximas de un HorizontalPodAutoscaler (límite de 1000 en el servidor) |
| POST | /resources/{type}/{ns}/{name}/edit-metadata | Editor | sí | Etiquetas y anotaciones: los equivalentes de kubectl label / kubectl annotate, en cualquier kind |
| POST | /resources/secrets/{ns}/{name}/reveal | Editor | sí | Decodifica los valores de un Secret. Admin en namespaces con patrón de producción; exige un motivo por escrito; se audita dos veces (ver abajo) |
| POST | /resources/{type}/{ns}/{name}/debug | Editor | sí | Adjunta un contenedor de depuración efímero a un pod en ejecución |
| POST | /resources/{type}/{ns}/{name}/cordon · /uncordon | Editor | sí | Activa o desactiva la planificación de pods en el nodo |
| POST | /resources/{type}/{ns}/{name}/evict | Editor | sí | Desaloja un pod mediante la Eviction API de policy/v1: 429 cuando lo bloquea un PDB |
| POST | /resources/{type}/{ns}/{name}/rollout-pause · /rollout-resume | Editor | sí | Pausa o reanuda el rollout de un Deployment |
| POST | /resources/{type}/{ns}/{name}/suspend · /resume · /trigger | Editor | sí | Controles de CronJob |
| DELETE | /resources/{type}/{ns}/{name} | Admin | sí | Elimina. force=true fija un periodo de gracia de cero; orphan=true conserva los dependientes |
| POST · GET · DELETE | /resources/{type}/{ns}/{name}/drain | Admin | sí | Inicia el drenado de un nodo (un stream SSE), se vuelve a conectar al que está en curso o lo cancela |
Cuerpos habituales:
POST …/scale { "replicas": 3 }
POST …/rollback { "toRevision": 0 } // 0 o ausente = la revisión anterior
POST …/set-image { "images": [ { "container": "app", "image": "ghcr.io/acme/app:1.4.2" } ] }
Revelar un Secret
POST /resources/secrets/{ns}/{name}/reveal es el sustituto auditado de
kubectl get secret -o yaml | base64 -d. Lee del apiserver en lugar de la
caché de informers, para que una comprobación de rotación vea el valor actual;
recibe un cuerpo {"keys": ["…"], "reason": "…"} con un motivo de entre 10 y
500 caracteres, y emite dos registros de auditoría (uno en el log general de
acciones y otro en un canal dedicado a las revelaciones de secretos), y ninguno
de los dos contiene nunca un valor ni un hash de un valor. El comportamiento
completo está en
Vistas de recursos.
Insights
Todo excepto GET /insights se sirve sin un clúster conectado: el
historial tiene que responder también para clústeres que ya no existen.
GET /insights lee el motor en vivo, así que necesita el clúster. Consulta
Motor de insights.
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET | /insights | Cualquiera | sí | Insights activos del clúster: severity (critical, warning, info), resolved, includeMuted. Devuelve items, total, hiddenByProfile, profile. history=true lee en su lugar los registros persistidos (status, since, until) |
| GET | /insights/summary | Cualquiera | no | Estado de los insights por clúster para la vista de flota |
| GET | /insights/episodes | Cualquiera | no | Historial de episodios: status, severity, rule, cluster, since, until, limit, page |
| GET | /insights/episodes/{id} | Cualquiera | no | Un episodio con sus transiciones y su recurrencia |
| GET | /insights/operational-episodes | Cualquiera | no | Ráfagas agrupadas de forma determinista dentro de una ventana de tiempo |
| GET | /insights/operational-episodes/{id}/episodes | Cualquiera | no | Los episodios dentro de una ráfaga |
| GET | /insights/shift-report | Cualquiera | no | ”While you were away”, acotado a tu marca de presencia |
| POST | /account/dashboard-seen | Cualquiera | no | La señal de presencia que Home envía después de renderizar |
| GET | /insights/mutes | Cualquiera | no | Lista los silencios (cluster, since, until) |
| POST | /insights/mutes | Editor | no | Crea un silencio (auditado) |
| DELETE | /insights/mutes/{id} | Editor | no | Levanta un silencio (auditado) |
| GET | /admin/insight-policies | Admin | no | Capa de políticas por regla (category) |
| PUT · DELETE | /admin/insight-policies/{rule} | Admin | no | Define o restablece la política de una regla (auditado) |
Seguridad
El barrido persiste la superficie de seguridad, así que también responde sin un conector en vivo, y abarca toda la flota, de modo que un clúster caído no hace que el panel devuelva un 503.
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET | /findings | Cualquiera | no | Hallazgos de vulnerabilidades, configuraciones incorrectas y cumplimiento. Alcance: cluster, status; facetas: source, kind, severity, resourceName, resourceNamespace, group; page, pageSize |
| GET | /findings/workloads | Cualquiera | no | Los mismos hallazgos agregados por workload |
| GET | /findings/{fingerprint} | Cualquiera | no | Un hallazgo, incluso de un clúster que ya no existe (live: false) |
| GET | /runtime-events | Cualquiera | no | Eventos de runtime de Falco, los más recientes primero (since=24h o RFC 3339, limit, cluster, source, priority) |
| POST | /ingest/falco | Pública | no | Ingesta del webhook de Falco, con autenticación por token de ingesta del clúster dentro del handler: consulta Falco |
Métricas y red
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET | /metrics/query | Cualquiera | no | Consulta PromQL instantánea (query, time) contra el almacén de métricas, fijada al clúster seleccionado. scope=fleet la amplía a todos los clústeres que puedes leer |
| GET | /metrics/query_range | Cualquiera | no | Consulta PromQL de rango (query, start, end, step), con el mismo alcance |
| GET | /metrics/{type}/{ns}/{name} | Cualquiera | sí | CPU y memoria actuales de un pod (type = pods) o de un nodo (nodes) desde Metrics Server. El historial está en /metrics/query_range |
| GET | /flows/edges | Cualquiera | no | Aristas de flujos de red de Hubble, cuando el agente envía flujos (namespace, window) |
| GET | /deploys | Cualquiera | sí | Rollouts detectados en una ventana de tiempo (windowMinutes) |
| GET | /right-sizing | Cualquiera | sí | Recomendaciones de rightsizing para los workloads del clúster: las que muestran las pantallas Capacity y Cost |
| POST | /prom/write | Pública | no | Ingesta de Prometheus remote-write. Desactivada salvo que KUBEBOLT_REMOTE_WRITE_ENABLED=true; token de ingesta bearer según KUBEBOLT_REMOTE_WRITE_AUTH_MODE (por defecto disabled): consulta Métricas |
Port-forward
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| POST | /portforward | Editor | sí | Abre un forward: campos del cuerpo namespace, pod, container (opcional), remotePort |
| GET | /portforward | Cualquiera | sí | Lista los forwards activos |
| DELETE | /portforward/{id} | Editor | sí | Detiene un forward |
| ANY | /pf/{id}/* | ninguno | no | Proxy inverso HTTP hacia el puerto redirigido, montado en la raíz, no bajo /api/v1. Lo autoriza la cookie kb_pf que se fija al abrir el forward |
POST /portforward abre un listener TCP real en el host del backend
mediante client-go, con un máximo de 20 forwards simultáneos. Lo que el
navegador puede alcanzar es el proxy inverso HTTP en /pf/{id}/, que es la
superficie que usa el panel; un cliente TCP puro (psql, mysql) tendría que
llegar a la red del propio backend. Consulta
Clústeres remotos para el
caso con túnel y sus limitaciones.
Helm
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET | /helm/releases | Cualquiera | sí | Todos los releases del clúster |
| GET | /helm/releases/{ns}/{name} | Cualquiera | sí | Detalle de una release (values, manifiesto, historial, dependencias), con los values y el manifiesto enmascarados como en la vista YAML: consulta Helm |
Kobi y MCP
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| POST | /mcp | Cualquiera | no | Servidor MCP: las herramientas de solo lectura de Kobi sobre Streamable HTTP, para claves de API. Funciona con el clúster caído; en ese caso, la llamada a la herramienta lo informa |
| POST | /copilot/chat | Cualquiera | no | Chat de Kobi como stream de Server-Sent Events: el chat de la interfaz. Responde incluso sin ningún clúster conectado |
| POST | /copilot/compact | Cualquiera | no | Resume una conversación larga |
| GET | /copilot/conversations | Cualquiera | no | Tus conversaciones (q, cluster, archived, limit) |
| GET · PATCH · DELETE | /copilot/conversations/{id} | Cualquiera | no | Lee, renombra o archiva, o elimina una de tus conversaciones |
| GET | /copilot/conversations/{id}/feedback | Cualquiera | no | Tus valoraciones en una conversación |
| POST | /copilot/feedback | Cualquiera | no | Valora una respuesta de Kobi (up, down, o vacío para retirar la valoración) |
Cuenta
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET | /account/plan | Cualquiera | no | Tu organización, su plan y sus límites |
| GET | /account/usage | Cualquiera | no | Uso medido (vacío en la edición open source) |
| GET | /account/capabilities | Cualquiera | no | Estados de las capacidades que hay detrás del banner de truncado (el límite de series activas) |
Integraciones y agentes
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET | /integrations · /integrations/{id} | Cualquiera | no | Integraciones detectadas (OpenCost, Hubble, …); solo metadatos cuando no hay ningún clúster conectado, para que el catálogo se siga mostrando |
| POST | /integrations/{id}/install | Admin | sí | Instala mediante el asistente (auditado) |
| GET · PUT | /integrations/{id}/config | Admin | sí | Configuración de la integración |
| DELETE | /integrations/{id} | Admin | sí | Desinstala |
| GET | /integrations/agent/install-defaults | Admin | no | Valores que el asistente Add cluster incluye en el comando de helm |
| GET | /integrations/agent/auth-info | Admin | no | Qué modo de autenticación del canal espera el backend |
| POST | /integrations/agent/issue-token | Admin | no | Emite un token de ingesta para un clúster nuevo |
| GET | /admin/agents | Admin | no | Agentes conectados en este momento |
Autenticación, usuarios y equipos
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| POST | /auth/logout | Cualquiera | no | Revoca el token de refresco y borra la cookie |
| GET | /auth/me | Cualquiera | no | Usuario actual |
| PUT | /auth/me/password | Cualquiera | no | {"currentPassword": "…", "newPassword": "…"} (al menos 8 caracteres); revoca tus otras sesiones |
| GET · POST | /users | Admin | no | Lista los usuarios; crea uno: campos del cuerpo username, email, name, password, role |
| GET · PUT · DELETE | /users/{id} | Admin | no | Lee, actualiza (username, email, name, role), elimina |
| PUT | /users/{id}/password | Admin | no | {"password": "…"}; revoca las sesiones de ese usuario |
| GET | /teams · /teams/{id} | Cualquiera | no | Equipos. La edición open source tiene un único equipo por defecto; POST /teams responde 409 requires_ee |
| GET | /teams/{id}/members | Admin | no | Los miembros de un equipo |
Administración
| Método | Endpoint | Rol | En vivo | Descripción |
|---|---|---|---|---|
| GET · POST | /admin/api-tokens | Admin | no | Lista y crea tokens de API. Ningún token de API puede llamar a estas rutas |
| DELETE | /admin/api-tokens/{id} | Admin | no | Revoca un token |
| PATCH | /admin/api-tokens/{id}/clusters | Admin | no | Sustituye la lista de clústeres de una clave de API: {"clusters": ["<cluster id>"]} |
| GET · POST · PUT · DELETE | /admin/tenants[/{id}], /admin/tenants/{id}/tokens[/{tokenID}], POST …/tokens/{tokenID}/rotate, /admin/tenants/{id}/limits | Admin | no | Tokens del agente (de ingesta) y límites de remote-write por tenant: la pestaña Agent Tokens |
| GET | /admin/actions | Admin | no | El registro de auditoría, lo más reciente primero: class=mutation|access|all, limit (100 por defecto, 1000 como máximo). No hay página de auditoría en la interfaz; consulta Registro de auditoría |
GET · PUT, POST …/reset | /admin/settings/{copilot,notifications,auth,general,ingest-channel} | Admin | no | Ajustes editables desde la interfaz que prevalecen sobre el entorno (auditado) |
| GET · PUT | /admin/settings/blocked-operations | Admin | no | Operaciones de los conectores de nube que ninguna llamada puede ejecutar: {"connectors": {"aws": ["s3.getobject"]}}; consulta Conectores de nube. Auditado |
| GET | /admin/settings/booted-with | Admin | no | El entorno KUBEBOLT_* con el que arrancó la API, con los secretos enmascarados |
| GET · POST | /admin/setup/status · /admin/setup/complete | Admin | no | Estado del Setup Wizard del primer inicio de sesión |
| POST | /admin/system/restart | Admin | no | Termina limpiamente para que Kubernetes reinicie la API con los ajustes guardados ya aplicados (202) |
| GET | /admin/copilot/usage/{summary,timeseries,sessions} | Admin | no | Analíticas de uso de Kobi |
| GET | /admin/metrics/query · /admin/metrics/query_range | Admin | no | PromQL sobre las métricas de ingesta propias de la instalación, sin fijar a un clúster |
GET · PUT · DELETE, POST …/test | /admin/mcp-connectors[/{id}] | Admin | no | Conectores de nube para Kobi. 404 cuando la función está desactivada |
| GET · POST | /notifications/config · /notifications/test/{channel} | Admin | no | Estado de los canales de notificación y un envío de prueba |
En KubeBolt Cloud, /admin/settings/auth, /admin/settings/ingest-channel,
/admin/setup y /admin/system los gestiona KubeBolt y responden 404 a los
Admin de las organizaciones.
Solo en Cloud
KubeBolt Cloud añade la gestión de organizaciones y equipos. Las rutas que probablemente necesite un script:
| Método | Endpoint | Rol | Descripción |
|---|---|---|---|
| GET | /auth/me/teams | Cualquiera | Tus equipos y tu rol en cada uno |
| POST | /teams | Admin | Crea un equipo |
| PUT · DELETE | /teams/{id} | Admin (renombrar: también el admin del equipo) | Renombra o elimina un equipo |
| POST · DELETE | /teams/{id}/members[/{userId}] | Admin o el admin del equipo | Agrega un miembro (campos del cuerpo userId y, opcional, role) o quita uno |
| PUT | /clusters/{clusterId}/team | Admin | Asigna un clúster a un equipo: {"teamId": "…"}, o vacío para quitar la asignación |
| PUT | /clusters/{clusterId}/environment | Admin | {"environment": "production"}: production, staging, testing, development o vacío |
| GET · PUT | /account/notifications | Cualquiera | Tu propia preferencia para no recibir notificaciones |
Tiempo real
| Método | Endpoint | Descripción |
|---|---|---|
| WS | /api/v1/ws | Notificaciones de cambios: consulta Eventos WebSocket |
| WS | /ws/exec/{ns}/{name} | Terminal del pod (Editor), montada en la raíz, no bajo /api/v1; consulta Eventos WebSocket |