KubeBolt docs
ENES GitHub

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
  1. Resumen
  2. Roles
  3. Gestión de sesiones
  4. Almacenamiento
  5. Variables de entorno
  6. Configuración de Helm
  7. Contraseña de admin olvidada
  8. Desactivar la autenticación
  9. En KubeBolt Cloud

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ónViewerEditorAdmin
Ver recursos, YAML, describe, eventos, métricas, topología, insights, hallazgos de seguridadSíSíSí
Ver logs de podsSíSíSí
Chatear con Kobi CopilotSíSíSí
Cambiar de clústerSíSíSí
Ejecutar una propuesta de KobiNoSíSí
Terminal del pod (exec) y contenedores de depuración efímerosNoSíSí
Explorar y descargar archivos de pods (auditado)NoSíSí
Editar YAML, crear recursos desde un manifiestoNoSíSí
Reiniciar, escalar, hacer rollback, cambiar imagen / recursos / variables de entorno, cordon, evictNoSíSí
Revelar el valor de un SecretNoSí (Admin en namespaces de producción)Sí
Silenciar un insightNoSíSí
Port forwardingNoSíSí
Eliminar recursosNoNoSí
Drenar un nodoNoNoSí
Agregar / renombrar / eliminar clústeresNoNoSí
Instalar, configurar o quitar integracionesNoNoSí
Gestionar usuarios, tokens de API y tokens del agenteNoNoSí
Cambiar ajustes (autenticación, IA, notificaciones, reglas de insights)NoNoSí
Leer el registro de auditoría y las analíticas de uso de KobiNoNoSí

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:

El último Admin no se puede degradar ni eliminar, y nadie puede eliminar su propia cuenta.

Gestión de sesiones

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

VariableValor por defectoDescripción
KUBEBOLT_AUTH_ENABLEDtruePonla en false para permitir el acceso anónimo; consulta Desactivar la autenticación.
KUBEBOLT_ADMIN_PASSWORDgenerada automáticamenteContraseñ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_SECRETgenerada automáticamenteClave 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_EXPIRY15mVida útil del token de acceso (duración de Go).
KUBEBOLT_JWT_REFRESH_EXPIRY168hVida útil del token de refresco.
KUBEBOLT_DATA_DIR./dataDirectorio de kubebolt.db. El chart y las imágenes usan /data.
KUBEBOLT_RESET_ADMIN_PASSWORDsin definirVí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: