Authentication — KubeBolt Docs

Overview

KubeBolt ships with a built-in auth system that supports three roles: Admin, Editor, and Viewer. Auth is enabled by default and uses BoltDB for user storage — no external database needed. Sessions are managed via JWT tokens stored in httpOnly cookies.

First boot: A default admin user is seeded automatically on first startup. The generated password is printed to the server logs. Change it immediately after first login.

Roles

KubeBolt enforces three roles with increasing levels of access:

Action	Viewer	Editor	Admin
View resources, metrics, topology, insights	Yes	Yes	Yes
View pod logs	Yes	Yes	Yes
Use AI Copilot (read-only tools)	Yes	Yes	Yes
Pod terminal (exec)	No	Yes	Yes
Edit YAML / Apply changes	No	Yes	Yes
Restart / Scale workloads	No	Yes	Yes
Delete resources	No	Yes	Yes
Port forwarding	No	Yes	Yes
Switch clusters	No	Yes	Yes
Manage users (create, edit, delete)	No	No	Yes
Change auth settings	No	No	Yes

Session Management

JWT tokens issued on login, stored in httpOnly secure cookies (not localStorage)
Token expiry is configurable (default: 24 hours)
Tokens are validated on every API request via auth middleware
Logout invalidates the cookie client-side

Storage

User accounts are stored in a local BoltDB file. By default, the database is written to ./data/kubebolt.db. Use the KUBEBOLT_DATA_DIR environment variable to customize the storage path. In Kubernetes deployments, mount a PersistentVolume to this path for durability.

Environment Variables

Variable	Default	Description
`KUBEBOLT_AUTH_ENABLED`	`true`	Enable or disable authentication. Set to `false` to allow anonymous access.
`KUBEBOLT_ADMIN_PASSWORD`	auto-generated	Override the default admin password on first boot. Ignored if admin user already exists.
`KUBEBOLT_JWT_SECRET`	auto-generated	Secret key for signing JWT tokens. Auto-generated and persisted in BoltDB if not set.
`KUBEBOLT_DATA_DIR`	`./data`	Directory for BoltDB storage file.

Helm Configuration

When deploying via Helm, configure auth through values:

# values.yaml
auth:
  enabled: true
  adminPassword: "my-secure-password"

# Or use an existing Kubernetes secret
auth:
  enabled: true
  existingSecret: "kubebolt-auth-secret"
  # Secret must contain keys: admin-password, jwt-secret

# Install with inline password
helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --set auth.adminPassword="my-secure-password"

# Install with existing secret
helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --set auth.existingSecret=kubebolt-auth-secret

Disabling Authentication

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

# Local development
KUBEBOLT_AUTH_ENABLED=false go run cmd/server/main.go --kubeconfig ~/.kube/config

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

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

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.