Configuración
Autenticación
Inicio de sesión integrado con los roles Admin, Editor y Viewer: primer arranque, sesiones, valores de Helm, cómo recuperar una contraseña de admin perdida y qué cambia en KubeBolt Cloud.
En esta página
Resumen
KubeBolt incluye un sistema de autenticación propio con tres roles: Admin, Editor y Viewer. La autenticación viene activada por defecto y guarda los usuarios en un archivo BoltDB embebido, así que no hay que mantener ninguna base de datos externa ni ningún proveedor de identidad. Una sesión es un token de acceso JWT de corta duración más un token de refresco que rota y viaja en una cookie httpOnly.
La edición open source solo admite inicio de sesión con usuarios y contraseñas locales: no hay inicio de sesión con OIDC, OAuth ni SSO, y todos los usuarios pertenecen a un único equipo por defecto. El inicio de sesión con cuentas sociales, las organizaciones y los equipos dueños de clústeres forman parte de KubeBolt Cloud. Para scripts, CI y hosts MCP, usa tokens de API en lugar de una sesión de usuario.
Primer arranque: KubeBolt crea un usuario llamado admin la primera vez
que arranca. Salvo que hayas indicado la contraseña (KUBEBOLT_ADMIN_PASSWORD
o auth.adminPassword en el chart), genera una, la imprime una sola vez
en el log de la API y, cuando corre dentro del clúster, la guarda en el
Secret kubebolt-admin-password (claves username y password) de su propio
namespace. Nunca sobrescribe un Secret existente con ese nombre. El
Setup Wizard del primer inicio de sesión
ofrece cambiar la contraseña; si perdiste las dos copias, consulta
Contraseña de admin olvidada.
kubectl -n kubebolt get secret kubebolt-admin-password \
-o jsonpath='{.data.password}' | base64 -d
Roles
KubeBolt aplica tres roles con niveles de acceso crecientes. La API comprueba el rol en cada petición; la interfaz solo oculta lo que no puedes usar.
| Acción | Viewer | Editor | Admin |
|---|---|---|---|
| Ver recursos, YAML, describe, eventos, métricas, topología, insights, hallazgos de seguridad | Sí | Sí | Sí |
| Ver logs de pods | Sí | Sí | Sí |
| Chatear con Kobi Copilot | Sí | Sí | Sí |
| Cambiar de clúster | Sí | Sí | Sí |
| Ejecutar una propuesta de Kobi | No | Sí | Sí |
| Terminal del pod (exec) y contenedores de depuración efímeros | No | Sí | Sí |
| Explorar y descargar archivos de pods (auditado) | No | Sí | Sí |
| Editar YAML, crear recursos desde un manifiesto | No | Sí | Sí |
| Reiniciar, escalar, hacer rollback, cambiar imagen / recursos / variables de entorno, cordon, evict | No | Sí | Sí |
| Revelar el valor de un Secret | No | Sí (Admin en namespaces de producción) | Sí |
| Silenciar un insight | No | Sí | Sí |
| Port forwarding | No | Sí | Sí |
| Eliminar recursos | No | No | Sí |
| Drenar un nodo | No | No | Sí |
| Agregar / renombrar / eliminar clústeres | No | No | Sí |
| Instalar, configurar o quitar integraciones | No | No | Sí |
| Gestionar usuarios, tokens de API y tokens del agente | No | No | Sí |
| Cambiar ajustes (autenticación, IA, notificaciones, reglas de insights) | No | No | Sí |
| Leer el registro de auditoría y las analíticas de uso de Kobi | No | No | Sí |
Un Viewer nunca llega a material secreto: las vistas que puede abrir lo
ocultan como lo hace la vista YAML. Desde la 2.6.4 eso incluye la vista de una
release de Helm (sus values y su manifiesto renderizado), describe, los
values de Helm, los parámetros y el entorno de plugin de una Application de
Argo CD, y los eventos de runtime; el explorador de archivos del pod ejecuta
comandos en el contenedor, así que necesita Editor, como la terminal. Revelar
un valor exige Editor, un motivo escrito y un registro de auditoría.
Consulta Acciones y gobernanza para ver la lista completa de acciones y el rol que necesita cada una, y la referencia de la API REST para ver el rol que exige cada ruta.
Hay dos cosas que el rol no hace:
- No cambia lo que KubeBolt puede hacer en el clúster. Toda acción se ejecuta con las credenciales de Kubernetes propias de KubeBolt (su ServiceAccount, el contexto de kubeconfig o el agente), nunca como el usuario que inició sesión. Una acción necesita un rol que la permita y permisos en el clúster que la permitan; consulta RBAC y permisos.
- Se lee del token de acceso. Un cambio de rol o un usuario eliminado surte efecto la próxima vez que se refresca el token de acceso de ese usuario, es decir, dentro de la vida útil del token de acceso (15 minutos por defecto). Restablecer la contraseña de un usuario desde Administration → Access → Users también cierra sus sesiones en el siguiente refresco.
El último Admin no se puede degradar ni eliminar, y nadie puede eliminar su propia cuenta.
Gestión de sesiones
POST /api/v1/auth/logindevuelve un token de acceso JWT en el cuerpo JSON (accessToken). La interfaz lo guarda en memoria (nunca en localStorage) y lo envía comoAuthorization: Bearer.- El token de refresco vive en la cookie
kb_refresh: httpOnly,SameSite=Strict, limitada a/api/v1/authySecurecuando la petición llegó por HTTPS. En el servidor se guarda como hash y rota en cada refresco. - Vida útil:
KUBEBOLT_JWT_EXPIRY(acceso, por defecto15m) yKUBEBOLT_JWT_REFRESH_EXPIRY(refresco, por defecto168h, 7 días). Las dos se pueden editar también en Administration → Access → Authentication; un cambio hecho allí se aplica tras reiniciar la API, y la página lo indica. - Cada petición autenticada valida el token de acceso en un middleware.
- Cerrar sesión elimina el token de refresco en el servidor y borra la cookie.
- Cambiar tu propia contraseña (Change password en el menú de la cuenta) revoca el token de refresco de todas las demás sesiones y conserva la actual.
- El inicio de sesión se limita por nombre de usuario: cinco intentos seguidos
y después uno cada 15 segundos. Los intentos de más reciben
429con una cabeceraRetry-After.
El formulario de inicio de sesión acepta un nombre de usuario o un correo electrónico, si la cuenta tiene uno. Los scripts pueden iniciar sesión de la misma manera, pero un token de API encaja mejor: no caduca cada 15 minutos y lleva sus propios scopes.
curl -s -X POST https://kubebolt.example.com/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"…"}' | jq -r .accessToken
Almacenamiento
Los usuarios, los tokens de refresco, los tokens de API y del agente, los
ajustes guardados desde la interfaz, las conversaciones de Kobi, el historial
de insights y los hallazgos de seguridad viven en un solo archivo BoltDB,
kubebolt.db, dentro de KUBEBOLT_DATA_DIR (por defecto ./data). El chart
de Helm usa /data y monta un PersistentVolumeClaim (<release>-data,
auth.persistence, 1Gi ReadWriteOnce por defecto); la imagen de un solo
contenedor lo guarda en su volumen /data.
BoltDB admite un solo escritor, así que ejecuta una sola réplica de la API. El
chart usa por defecto replicaCount: 1 y la estrategia Recreate, de modo que
una actualización nunca arranca un pod nuevo mientras el anterior todavía
tiene el bloqueo.
Variables de entorno
| Variable | Valor por defecto | Descripción |
|---|---|---|
KUBEBOLT_AUTH_ENABLED | true | Ponla en false para permitir el acceso anónimo; consulta Desactivar la autenticación. |
KUBEBOLT_ADMIN_PASSWORD | generada automáticamente | Contraseña del usuario admin; solo se usa cuando ese usuario se crea por primera vez. Si está definida, no se imprime nada ni se escribe ningún Secret. |
KUBEBOLT_JWT_SECRET | generada automáticamente | Clave que firma los tokens de acceso. Debe tener al menos 32 bytes; un valor más corto detiene la API al arrancar. Si no está definida, se genera una clave aleatoria y se persiste en BoltDB. |
KUBEBOLT_JWT_EXPIRY | 15m | Vida útil del token de acceso (duración de Go). |
KUBEBOLT_JWT_REFRESH_EXPIRY | 168h | Vida útil del token de refresco. |
KUBEBOLT_DATA_DIR | ./data | Directorio de kubebolt.db. El chart y las imágenes usan /data. |
KUBEBOLT_RESET_ADMIN_PASSWORD | sin definir | Vía de recuperación: si está definida, la API restablece la contraseña de admin a este valor al arrancar y después arranca con normalidad. El chart la toma de auth.resetAdminPassword. Bórrala en cuanto hayas iniciado sesión. |
El secreto JWT también deriva la clave que cifra los secretos guardados desde la interfaz (claves de proveedores de IA, URLs de webhooks). Cambiarlo cierra la sesión de todo el mundo y deja esos valores ilegibles: vuelve a introducirlos después. La lista completa de variables está en Variables de entorno.
Configuración de Helm
Si despliegas con Helm, configura la autenticación con los values del chart:
# values.yaml
auth:
enabled: true
adminPassword: "my-secure-password" # solo en el primer arranque; se genera si está vacío
jwtSecret: "" # se genera y se persiste si está vacío
existingSecret: "" # ver más abajo
resetAdminPassword: "" # solo para recuperación
persistence:
enabled: true
size: 1Gi
storageClass: ""
Para mantener las credenciales fuera de tu archivo de values, apunta
auth.existingSecret a un Secret que gestiones tú. Puede contener
admin-password, jwt-secret o las dos; si falta una clave, se usa el valor
generado por defecto.
kubectl -n kubebolt create secret generic kubebolt-auth-secret \
--from-literal=admin-password='my-secure-password' \
--from-literal=jwt-secret="$(openssl rand -hex 32)"
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --create-namespace \
--set auth.existingSecret=kubebolt-auth-secret
O en línea, para una prueba rápida:
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --create-namespace \
--set auth.adminPassword="my-secure-password"
Contraseña de admin olvidada
La línea del log del primer arranque se imprime una sola vez y el Secret del
primer arranque no refleja los cambios de contraseña posteriores, así que
KubeBolt trae dos vías de recuperación. Las dos fijan una contraseña nueva para
el usuario llamado admin, y la contraseña nueva necesita al menos
8 caracteres.
Vía A: helm upgrade. Define KUBEBOLT_RESET_ADMIN_PASSWORD en el
Deployment; la API restablece la contraseña en el siguiente arranque del pod,
la escribe en el log y continúa con su arranque normal. La
strategy: Recreate del chart garantiza que el pod anterior ya no existe (y
que el bloqueo de BoltDB está liberado) antes de que el nuevo haga el
restablecimiento.
helm upgrade kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --reset-then-reuse-values --set auth.resetAdminPassword=NEWPASS
# inicia sesión con NEWPASS, cambia a tu contraseña real desde el menú de la cuenta y luego
# borra el valor para que no se quede en los values de la release:
helm upgrade kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --reset-then-reuse-values --set auth.resetAdminPassword=
Vía B: un Job de una sola ejecución, para runbooks o instalaciones que no
gestiona Helm. BoltDB admite un solo escritor, así que primero hay que escalar
la API a cero. Los nombres de abajo suponen que la release se llama kubebolt
(Deployment kubebolt-api, PVC kubebolt-data):
NS=kubebolt # el namespace de tu release
IMAGE=$(kubectl -n $NS get deploy/kubebolt-api -o jsonpath='{.spec.template.spec.containers[0].image}')
kubectl -n $NS scale deploy/kubebolt-api --replicas=0
kubectl -n $NS apply -f - <<EOF
apiVersion: batch/v1
kind: Job
metadata: { name: kubebolt-pw-reset }
spec:
ttlSecondsAfterFinished: 60
template:
spec:
restartPolicy: Never
containers:
- name: reset
image: $IMAGE
command: ["kubebolt-api", "--reset-admin-password=NEWPASS"]
env: [{ name: KUBEBOLT_DATA_DIR, value: /data }]
volumeMounts: [{ name: data, mountPath: /data }]
volumes:
- name: data
persistentVolumeClaim: { claimName: kubebolt-data }
EOF
kubectl -n $NS wait --for=condition=Complete job/kubebolt-pw-reset --timeout=60s
kubectl -n $NS scale deploy/kubebolt-api --replicas=1
La misma opción funciona con el binario único:
kubebolt --reset-admin-password=NEWPASS restablece la contraseña y termina
sin arrancar ningún servidor. Con Docker Compose, detén el servicio api y
pasa la opción a un contenedor puntual:
docker compose stop api
docker compose run --rm api --reset-admin-password=NEWPASS
docker compose start api
Desactivar la autenticación
Para ejecutar KubeBolt sin autenticación (por ejemplo, detrás de una VPN o en desarrollo local):
# Desarrollo local (desde apps/api)
KUBEBOLT_AUTH_ENABLED=false go run ./cmd/server --kubeconfig ~/.kube/config
# Docker Compose (defínela en tu shell o en deploy/.env)
KUBEBOLT_AUTH_ENABLED=false
# Helm
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--set auth.enabled=false
Con la autenticación desactivada, cada petición se trata como Admin y el
almacén BoltDB ni siquiera se abre. Eso apaga todo lo que vive en él:
usuarios, tokens de API y del agente, ajustes guardados desde la interfaz (los
ajustes de Administration devuelven 503), el historial de conversaciones de
Kobi, el historial de episodios de insights, y los hallazgos de seguridad y
eventos de runtime persistidos.
Advertencia: desactivar la autenticación expone todas las capacidades de gestión del clúster a cualquiera que pueda llegar a la interfaz de KubeBolt. Desactívala solo cuando el acceso ya esté restringido a nivel de red.
En KubeBolt Cloud
KubeBolt Cloud usa los mismos roles y el mismo modelo de sesión, con las piezas que necesita un servicio con varias organizaciones:
- Inicio de sesión. Correo y contraseña, o Continue with Google,
Microsoft o GitHub. Tu organización no tiene usuario
adminde arranque ni recuperación por Helm: una contraseña olvidada se restablece desde Forgot password? en la página de inicio de sesión (el enlace que llega por correo vale una hora). - Verificación del correo. Hasta que verifiques tu correo, el chat de Kobi,
invitar usuarios, crear equipos y emitir tokens de API o del agente
responden
403con"code": "email_unverified". - Organizaciones. Cada registro crea una organización, y su primer usuario es su Admin. Los Admin invitan a sus compañeros por correo (el enlace de invitación vale siete días) y eligen el rol de organización de cada uno.
- Los equipos son dueños de los clústeres. Un Admin asigna cada clúster a un equipo desde la página Clusters (Assign team). Los Admin ven todos los clústeres de la organización; quienes tienen rol Editor o Viewer ven los clústeres de sus equipos. Un clúster que todavía no tiene equipo asignado solo lo ven los Admin.
- Los ajustes de toda la instalación los gestionamos nosotros. La política
de inicio de sesión, la vida útil de los tokens y el canal de ingesta del
agente los opera KubeBolt, no el Admin de una organización. Los tokens de
servicio (
kbs_) no se emiten a organizaciones; las claves de API (kbk_) sí: consulta Tokens de API.