KubeBolt docs
ENES GitHub

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
  1. Dos tipos
  2. Crear uno
  3. Usar uno
  4. Scopes
  5. Acceso por clúster
  6. La restricción del edge público
  7. Revocar

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_
ParaClientes 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 crearloUn Admin. No disponible para organizaciones en KubeBolt CloudUn Admin (en Cloud, con el correo verificado)
Roleditor, salvo que la petición indique otroSe elige en el formulario (viewer preseleccionado). Por la API, editor si se omite
Scopes por defectoEl conjunto de servicio (ver abajo)Ninguno: los eliges tú
Lista de clústeresNinguna: lee todos los clústeresOpcional (ver abajo)
A través del edge públicoRechazadoFunciona

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:

  1. 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 api es 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.
  2. 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:

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.