Configuración
Tokens de API
Tokens de servicio kbs_ y claves de API kbk_: cómo crearlos, qué scopes y listas de clústeres llevan y por qué se rechaza un token de servicio cuando llega desde internet.
En esta página
Los tokens de la API REST autentican a clientes no interactivos contra
/api/v1/* sin una sesión de usuario. Se crean y se revocan en
Administration → API Tokens (/admin/api-tokens, rol Admin).
No son lo mismo que los tokens de ingesta que usan el agente y
Falco. Esos empiezan por kb_, viven en un almacén aparte y
se emiten desde Administration → Agents & Ingest → Agent Tokens. Los dos
almacenes nunca se cruzan: un token de ingesta nunca puede autenticar una
llamada REST, y un token REST nunca puede autenticar el canal del agente. Ese
aislamiento es, en sí mismo, una propiedad de seguridad.
Dos tipos
Token de servicio kbs_ | Clave de API kbk_ | |
|---|---|---|
| Para | Clientes máquina internos que llegan a la API directamente (de backend a backend, dentro de tu red) | Tus propias integraciones, CI/CD y hosts MCP |
| Quién puede crearlo | Un Admin. No disponible para organizaciones en KubeBolt Cloud | Un Admin (en Cloud, con el correo verificado) |
| Rol | editor, salvo que la petición indique otro | Se elige en el formulario (viewer preseleccionado). Por la API, editor si se omite |
| Scopes por defecto | El conjunto de servicio (ver abajo) | Ninguno: los eliges tú |
| Lista de clústeres | Ninguna: lee todos los clústeres | Opcional (ver abajo) |
| A través del edge público | Rechazado | Funciona |
Los dos se guardan como hashes SHA-256. El texto en claro (el prefijo seguido
de 32 caracteres aleatorios) se devuelve exactamente una vez, al crearlo, y
nunca se puede recuperar: cópialo en ese momento. La lista solo conserva un
prefijo para mostrar (kbk_ más los primeros 8 caracteres).
Los dos admiten una caducidad opcional. Déjala vacía para que no caduque; la revocación es inmediata en cualquier caso.
Crear uno
En la interfaz, elige New API token (o New service token), rellena Label y, para una clave de API, Role, Scopes, Clusters y, si quieres, Expires after (days). El token se muestra una sola vez en el diálogo siguiente.
O llama al endpoint con una sesión de admin. type es service o apikey
(por defecto service), ttlHours en 0 u omitido significa sin caducidad,
y clusters recibe ids de clúster; consulta
Acceso por clúster:
# un token de sesión de admin (los tokens de API no pueden crear tokens)
ADMIN_TOKEN=$(curl -s -X POST https://kubebolt.example.com/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"…"}' | jq -r .accessToken)
curl -X POST https://kubebolt.example.com/api/v1/admin/api-tokens \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-d '{
"label": "ci-readonly",
"type": "apikey",
"role": "viewer",
"scopes": ["/api/v1/resources", "/api/v1/insights"],
"ttlHours": 720
}'
La respuesta 201 trae el texto en claro una sola vez, más los metadatos del
token:
{
"token": "kbk_…",
"apiToken": {
"id": "6f1c…", "prefix": "kbk_ab12cd34", "label": "ci-readonly",
"type": "apikey", "role": "viewer",
"scopes": ["/api/v1/resources", "/api/v1/insights"],
"createdAt": "…", "createdBy": "…", "expiresAt": "…"
}
}
Cada emisión, cambio de la lista de clústeres y revocación queda en el registro
de auditoría de administración (GET /api/v1/admin/actions) con la etiqueta,
el tipo, el rol, los scopes y los clústeres (nunca el token), lo suficiente
para que un revisor juzgue si la concesión era apropiada.
Usar uno
Envíalo como bearer token, exactamente igual que un token de sesión:
curl -H "Authorization: Bearer $KUBEBOLT_TOKEN" \
"https://kubebolt.example.com/api/v1/resources/deployments?namespace=shop"
Los tokens desconocidos, revocados y caducados (y un token de servicio que
llega por el edge público) reciben
401 {"error":"invalid or expired token"}. Una ruta fuera de los scopes del
token, o por encima de su rol, recibe 403. La
referencia de la API REST lista cada ruta con el rol que
necesita.
Scopes
Un scope es un prefijo de ruta URL. Un token puede llamar a una ruta
cuando alguno de sus scopes es prefijo de ella: /api/v1/resources cubre
/api/v1/resources/deployments/shop/checkout/scale. * concede todas las
rutas autenticadas. Un conjunto de scopes vacío lo deniega todo: la
comprobación falla de forma segura (fail closed).
Los scopes se suman por encima del rol, no lo sustituyen: un token viewer
con scope * sigue sin poder escribir.
Un token de servicio creado sin scopes explícitos recibe el conjunto de servicio:
/api/v1/cluster/overview
/api/v1/insights
/api/v1/events
/api/v1/resources
/api/v1/mcp
Las opciones predefinidas del formulario para claves de API son
Cluster overview, Resources, Insights, Events y Metrics
(/api/v1/metrics), más dos opciones que cubren toda una superficie:
MCP only (read-only tools), que se reduce a /api/v1/mcp y nada más, y
Everything (all authenticated paths), que se reduce a *.
MCP only es la opción indicada cuando un host solo necesita leer. Fija el
rol del token en viewer en el servidor, pida lo que pida la petición que lo
crea, y por defecto caduca a los 90 días. Antes de la 2.2, la única forma de
llegar al servidor MCP desde el formulario era Everything, que entregaba
toda la API a una clave que solo necesitaba herramientas de solo lectura; si
configuraste un host MCP de esa forma, sustituye su clave.
Ningún token de API puede llegar a /api/v1/admin/api-tokens, digan lo
que digan sus scopes. Las credenciales las crea, edita y revoca un admin con
sesión iniciada, así que un token filtrado no puede emitirse a sí mismo uno
más amplio.
Acceso por clúster
Una clave de API lee todos los clústeres de su organización, o solo los que se marcaron para ella (Every cluster in the organization / Only these clusters). La lista se define al crearla y se edita después desde el lápiz de la fila del token. Por la API:
curl -X PATCH https://kubebolt.example.com/api/v1/admin/api-tokens/$TOKEN_ID/clusters \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-d '{"clusters": ["3f9a2c1e-…"]}'
La lista contiene ids de clúster: el campo clusterId de
GET /api/v1/clusters, que es el UID del namespace kube-system del clúster.
Una lista vacía significa todos los clústeres, incluidos los que se agreguen
más adelante. Un contexto de kubeconfig que todavía no ha informado de su id
no se puede elegir. Los tokens de servicio no llevan lista y se rechazan
(400). Un cambio surte efecto en la siguiente petición del token; el token en
sí no cambia.
La lista se comprueba en cada ruta de lectura: el clúster que nombra una
petición, el clúster por defecto de una petición que no nombra ninguno, todo
lo que se acota por clúster (hallazgos, eventos de runtime, historial de
insights, ráfagas, silencios, el informe de turno, la ruta PromQL de toda la
flota) y las propias listas de clústeres, de modo que GET /api/v1/clusters y
el list_clusters de Kobi solo nombran lo que el token puede leer.
Una clave limitada a algunos clústeres también queda fuera de la
administración de toda la organización, sean cuales sean sus scopes y su rol:
/api/v1/admin/…, /api/v1/users, /api/v1/teams y /api/v1/account
responden 403, y lo mismo cualquier escritura bajo /api/v1/clusters.
Dentro de su lista, el cliente elige el clúster en cada petición:
curl -H "Authorization: Bearer $TOKEN" \
-H "X-KubeBolt-Cluster: prod-eu-west" \
https://kubebolt.example.com/api/v1/cluster/overview
El valor de la cabecera es el context del clúster tal como lo devuelve
GET /api/v1/clusters (agent: seguido del id del clúster, para un clúster
conectado por agente). Un clúster fuera de la lista recibe
403 you do not have access to this cluster. Si omites la cabecera, obtienes
el clúster seleccionado en ese momento en KubeBolt o, para una clave limitada
a algunos clústeres, el primero que puede leer cuando el seleccionado no está
en su lista.
La restricción del edge público
Un token de servicio kbs_ que llega por el edge público se rechaza,
aunque por lo demás sea válido.
El nginx incluido fuerza X-KubeBolt-Edge: public en todo lo que hace de
proxy (/api/, las rutas WebSocket y el proxy de port-forward) con
proxy_set_header, que sobrescribe lo que haya enviado el cliente. La ruta de
Gateway API del chart (gatewayAPI.enabled) la fija de la misma manera. La API
rechaza los tokens de servicio que llevan esa cabecera, así que un token kbs_
filtrado no sirve de nada desde internet.
De aquí se derivan dos cosas, y es fácil tropezar con las dos:
- Solo se cumple si a la API no se puede llegar más que a través del
proxy. El control supone que el Service
apies solo ClusterIP. Si expones la API directamente (un LoadBalancer, un Ingress que se salta el contenedor web incluido), la cabecera nunca se fija y la protección desaparece. Mantenla interna. - Los clientes internos no se ven afectados. Un cliente que llega al Service de la API dentro del clúster nunca lleva la cabecera. Tampoco la imagen de un solo contenedor, que no tiene nginx: así que no publiques una en internet con tokens de servicio emitidos.
En KubeBolt Cloud, https://api.kubebolt.io es un edge público: usa una clave
de API.
Qué significa esto para MCP sobre HTTP
El servidor MCP de solo lectura de Kobi
es POST /api/v1/mcp, y se autentica con tokens de API. El token que necesitas
depende de dónde corre el cliente:
- Dentro de la red: un job de CI en el mismo clúster, un agente que llama
directamente al Service de la API. Un token de servicio
kbs_funciona, y sus scopes por defecto ya incluyen/api/v1/mcp. - A través de la URL de la interfaz: Claude Code en un portátil, un agente
alojado, cualquier cosa que pase por el nginx incluido y cualquier cosa en
KubeBolt Cloud. Un token de servicio se rechazará en el edge. Usa una
clave de API
kbk_creada con MCP only, que es exactamente este caso:/api/v1/mcpcomo toda su superficie yviewercomo rol. Marca los clústeres que puede leer mientras estás en el diálogo. La solo lectura también se impone en el servidor, a partir del catálogo de herramientas, así que un cliente no puede invocar una herramienta que modifique nada, ni siquiera por su nombre.
Envía X-KubeBolt-Cluster junto con ella para apuntar a un clúster concreto.
Revocar
Elimina el token en la interfaz (lo confirmas escribiendo su etiqueta) o llama
a DELETE /api/v1/admin/api-tokens/{id}. La revocación surte efecto en la
siguiente petición; no hay ninguna concesión en caché que esperar a que
expire. Los tokens revocados y caducados se quedan en la lista con su estado,
junto al prefijo, la etiqueta, el rol, los scopes, los clústeres,
Last used y Expires de cada token, así que un token sin usar es fácil
de detectar y retirar.