KubeBolt docs
ENES GitHub

Configuration

Authentication

Built-in sign-in with Admin, Editor and Viewer roles: first boot, sessions, Helm values, recovering a lost admin password, and what changes on KubeBolt Cloud.

On this page
  1. Overview
  2. Roles
  3. Session Management
  4. Storage
  5. Environment Variables
  6. Helm Configuration
  7. Forgotten admin password
  8. Disabling Authentication
  9. On KubeBolt Cloud

Overview

KubeBolt ships with a built-in auth system and three roles: Admin, Editor and Viewer. Auth is on by default and keeps users in an embedded BoltDB file, so there is no external database or identity provider to run. A session is a short-lived JWT access token plus a rotating refresh token in an httpOnly cookie.

The open-source edition signs in with local usernames and passwords only — there is no OIDC, OAuth or SSO login, and every user belongs to one default team. Social sign-in, organizations and teams that own clusters are part of KubeBolt Cloud. For scripts, CI and MCP hosts, use API tokens instead of a user session.

First boot: KubeBolt creates a user named admin the first time it starts. Unless you supplied the password (KUBEBOLT_ADMIN_PASSWORD or the chart’s auth.adminPassword), it generates one, prints it once to the API log and, when it runs in-cluster, stores it in the Secret kubebolt-admin-password (keys username and password) in its own namespace. An existing Secret of that name is never overwritten. The first-login Setup Wizard offers to change the password; if you missed both copies, see Forgotten admin password.

kubectl -n kubebolt get secret kubebolt-admin-password \
  -o jsonpath='{.data.password}' | base64 -d

Roles

KubeBolt enforces three roles with increasing levels of access. The API checks the role on every request; the UI only hides what you cannot use.

ActionViewerEditorAdmin
View resources, YAML, describe, events, metrics, topology, insights, security findingsYesYesYes
View pod logsYesYesYes
Chat with Kobi CopilotYesYesYes
Switch clustersYesYesYes
Execute a Kobi proposalNoYesYes
Pod terminal (exec) and ephemeral debug containersNoYesYes
Browse and download pod files (audited)NoYesYes
Edit YAML, create resources from a manifestNoYesYes
Restart, scale, roll back, set image / resources / env, cordon, evictNoYesYes
Reveal a Secret valueNoYes (Admin in production namespaces)Yes
Mute an insightNoYesYes
Port forwardingNoYesYes
Delete resourcesNoNoYes
Drain a nodeNoNoYes
Add / rename / delete clustersNoNoYes
Install, configure or remove integrationsNoNoYes
Manage users, API tokens and agent tokensNoNoYes
Change settings (auth, AI, notifications, insight rules)NoNoYes
Read the audit trail and Kobi usage analyticsNoNoYes

A Viewer never reaches secret material: the views a Viewer can open hide it the way the YAML view does. Since 2.6.4 that covers the Helm release view (its values and rendered manifest), describe, an Argo CD Application’s Helm values, parameters and plugin environment, and runtime events; the pod file browser runs commands in the container, so it needs Editor, like the terminal. Revealing a value takes Editor, a written reason and an audit record.

See Actions & Governance for the full action list and the role each one needs, and the REST API reference for the role behind every route.

Two things the role does not do:

The last Admin cannot be demoted or deleted, and nobody can delete their own account.

Session Management

The login form takes a username — or an email, when the account has one. Scripts can sign in the same way, but an API token is the better fit: it does not expire every 15 minutes and carries its own 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

Storage

Users, refresh tokens, API and agent tokens, UI-saved settings, Kobi conversations, insight history and security findings all live in one BoltDB file, kubebolt.db, under KUBEBOLT_DATA_DIR (default ./data). The Helm chart sets /data and mounts a PersistentVolumeClaim (<release>-data, auth.persistence, 1Gi ReadWriteOnce by default); the single-container image keeps it in its /data volume.

BoltDB is single-writer, so run one API replica. The chart defaults to replicaCount: 1 and uses the Recreate strategy, so an upgrade never starts a new pod while the old one still holds the lock.

Environment Variables

VariableDefaultDescription
KUBEBOLT_AUTH_ENABLEDtrueSet to false to allow anonymous access — see Disabling Authentication.
KUBEBOLT_ADMIN_PASSWORDauto-generatedPassword for the admin user, used only when that user is first created. When set, nothing is printed and no Secret is written.
KUBEBOLT_JWT_SECRETauto-generatedKey that signs access tokens. Must be at least 32 bytes; a shorter value stops the API at boot. When unset, a random key is generated and persisted in BoltDB.
KUBEBOLT_JWT_EXPIRY15mAccess-token lifetime (Go duration).
KUBEBOLT_JWT_REFRESH_EXPIRY168hRefresh-token lifetime.
KUBEBOLT_DATA_DIR./dataDirectory for kubebolt.db. The chart and the images set /data.
KUBEBOLT_RESET_ADMIN_PASSWORDunsetRecovery hatch: when set, the API resets the admin password to this value at startup and then boots normally. The chart sets it from auth.resetAdminPassword. Clear it once you have logged in.

The JWT secret also derives the key that encrypts secrets saved from the UI (AI provider keys, webhook URLs). Changing it signs everyone out and leaves those values unreadable — enter them again afterwards. The full variable list is in Environment variables.

Helm Configuration

When deploying via Helm, configure auth through values:

# values.yaml
auth:
  enabled: true
  adminPassword: "my-secure-password"   # first boot only; generated if empty
  jwtSecret: ""                         # generated and persisted if empty
  existingSecret: ""                    # see below
  resetAdminPassword: ""                # recovery only
  persistence:
    enabled: true
    size: 1Gi
    storageClass: ""

To keep credentials out of your values file, point auth.existingSecret at a Secret you manage. It may carry admin-password, jwt-secret, or both; a key that is missing falls back to the generated default.

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

Or inline, for a quick test:

helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  -n kubebolt --create-namespace \
  --set auth.adminPassword="my-secure-password"

Forgotten admin password

The first-boot log line prints once and the first-boot Secret does not track later password changes, so KubeBolt ships two recovery paths. Both set a new password on the user named admin, and the new password needs at least 8 characters.

Path A — helm upgrade. Sets KUBEBOLT_RESET_ADMIN_PASSWORD on the deployment; the API resets the password at next pod start, logs it, and then continues its normal boot. The chart’s strategy: Recreate guarantees the old pod is gone — and the BoltDB lock released — before the new one runs the reset.

helm upgrade kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  -n kubebolt --reset-then-reuse-values --set auth.resetAdminPassword=NEWPASS

# log in with NEWPASS, change to your real password from the account menu, then
# clear the value so it doesn't sit in your release values:
helm upgrade kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  -n kubebolt --reset-then-reuse-values --set auth.resetAdminPassword=

Path B — a one-shot Job, for runbooks or installs not managed by Helm. BoltDB is single-writer, so the API has to be scaled to zero first. The names below assume the release is called kubebolt (deployment kubebolt-api, PVC kubebolt-data):

NS=kubebolt   # your release namespace
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

The same flag works on the single binary — kubebolt --reset-admin-password=NEWPASS resets the password and exits without starting a server. With Docker Compose, stop the api service and run the flag in a one-off container:

docker compose stop api
docker compose run --rm api --reset-admin-password=NEWPASS
docker compose start api

Disabling Authentication

To run KubeBolt without authentication (e.g., behind a VPN or for local development):

# Local development (from apps/api)
KUBEBOLT_AUTH_ENABLED=false go run ./cmd/server --kubeconfig ~/.kube/config

# Docker Compose (set in your shell or deploy/.env)
KUBEBOLT_AUTH_ENABLED=false

# Helm
helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --set auth.enabled=false

With auth off, every request is treated as Admin, and the BoltDB store is not opened at all. That turns off everything that lives in it: users, API and agent tokens, settings saved from the UI (the Administration settings return 503), Kobi conversation history, insight episode history, and persisted security findings and runtime events.

Warning: Disabling auth exposes full cluster management capabilities to anyone who can reach the KubeBolt UI. Only disable auth when access is already restricted at the network level.

On KubeBolt Cloud

KubeBolt Cloud runs the same roles and session model, with the pieces a multi-organization service needs: