Configuration

KubeGlass needs no configuration to run on your machine. Settings come from, in order of precedence:

1. KUBEGLASS_* environment variables (the setting name in upper case: log_level is KUBEGLASS_LOG_LEVEL),
2. a kubeglass.yaml (or .toml or .json) in the working directory, /etc/kubeglass/ or ~/.kubeglass/,
3. the defaults below.

The kubeconfig comes from $KUBECONFIG or ~/.kube/config. Inside a cluster KubeGlass uses its ServiceAccount.

In the Helm chart, config: in values.yaml has nine of them: logLevel, environment (env), authMode, adminUsers, adminGroups, readOnly, trustedProxies, allowedHosts and basePath. The OIDC settings are under oidc: and the session settings under session: (see Sign-in), the extensions file is the chart’s extensions: value, and prometheus.url and alertmanager.url set KUBEGLASS_PROMETHEUS_URL and KUBEGLASS_ALERTMANAGER_URL. Set anything else as an environment variable in extraEnv.

Server

Setting	Default
port	8090	HTTP port
bind_address	empty	Address to listen on. Empty means 127.0.0.1 in local auth mode outside a cluster, and all interfaces otherwise. The container image sets 0.0.0.0
base_path	empty	The path KubeGlass is served under, such as /kubeglass for https://tools.example.com/kubeglass/ (same as --base-path). Empty is the root. See Serving under a path
env	development	production turns on stricter validation (for example, the OIDC issuer must use HTTPS) and hides internal error details from API responses
log_level	info	trace, debug, info, warn, error
data_dir	~/.kubeglass/data (/var/lib/kubeglass/data in a cluster)	Where the bbolt databases, saved settings and, at a terminal, the log live
extensions_file	~/.kubeglass/extensions.yaml, or /etc/kubeglass/extensions.yaml without a home directory	Actions, list columns and palette aliases for the UI. See Extensions
demo_mode	false	Run on sample data (same as --demo)
read_only	false	Refuse every change, and turn off shells and port forwarding, whatever RBAC allows (same as --read-only). For shared screens and people who should only look. To make one cluster read-only for yourself, mark it on the Clusters page
metrics_enabled	true	Serve Prometheus metrics at /metrics, at the root of the pod (not under base_path). Off, /metrics answers 404. See Monitoring for who can reach it
tls_enabled, tls_cert, tls_key	off	Serve HTTPS with this certificate and key. Usually TLS ends at your ingress instead
cors_allowed_origins	empty	Comma-separated origins (https://dashboard.example.com) allowed to call the API from other sites. Empty blocks cross-origin requests. * is refused, since those requests carry the user’s credentials
allowed_hosts	empty	In local auth mode, extra host names KubeGlass answers to, comma-separated (*.example.com matches subdomains). Without a login it otherwise answers only to localhost, names under .localhost and IP addresses, which keeps DNS rebinding pages out. The chart adds the Service’s own names (<fullname>, <fullname>.<namespace>, <fullname>.<namespace>.svc), which clients in the cluster such as helm test ask, and its Ingress hosts
enable_pprof	false	Serve Go’s profiler at /debug/pprof/ on a separate listener, localhost:6060, not on the main port
KUBEGLASS_DRAIN_TIMEOUT	25s	How long shutdown may take: requests in flight finish, WebSockets close, background work stops and running Helm operations end (see Shutdown). The chart sets it to terminationGracePeriodSeconds less 5 seconds. A Go duration or a number of seconds
KUBEGLASS_SHUTDOWN_DELAY	0s	How long shutdown serves on with /readyz failing before it stops taking requests, so the Service’s endpoints and load balancers drop the pod first. It counts toward KUBEGLASS_DRAIN_TIMEOUT, at most half of it. The chart sets 5 seconds. A Go duration
KUBEGLASS_HEALTH_INTERVAL	30s	How often KubeGlass checks in the background that the API server answers, which opens and closes the circuit breaker

Sign-in and access

Setting	Default
auth_mode	local	local, oidc, token or impersonation. See Running for a team and Sign-in
admin_users, admin_groups	empty	Comma-separated users and groups who may add clusters, add chart repositories and update their indexes, change settings, and use the audit log and Drift policies. In local mode the user is always an admin
session_max_age	4h	How long an idle browser session lasts: its chosen cluster and namespace, and in oidc and token modes its sign-in. Typing into a shell counts as use, also in a tab in the background; an open log stream or watch doesn’t
session_lifetime	24h	In oidc and token modes, the longest a sign-in lasts however active it is
session_key	generated	32 random bytes, base64-encoded, that encrypt sign-in sessions in the data directory. When empty, KubeGlass generates session.key there. Set it from a Secret
logout_url	empty	Where “Sign out” sends the browser behind a sign-in proxy, used as written (base_path isn’t added). In oidc and token modes Sign out ends KubeGlass’s own session
oidc_issuer_url	empty	The provider’s issuer. Required for oidc
oidc_client_id, oidc_client_secret	empty	KubeGlass’s client at the provider. The ID is required for oidc (or oidc_audience); without a secret it is a public client
oidc_redirect_url	empty	The redirect URI registered at the provider, KubeGlass’s address followed by /auth/callback (under base_path when there is one); HTTPS in production. Without it, browser sign-in is off and oidc accepts bearer tokens only
oidc_scopes	openid profile email	Scopes asked for at sign-in, separated by spaces or commas
oidc_audience	the client ID	The audience a bearer token in an Authorization header must have
oidc_required_scopes	empty	Scopes a bearer token must carry in its scope or scp claim
oidc_user_claim, oidc_groups_claim	sub, groups	ID token claims for the user name and groups
oidc_username_prefix, oidc_groups_prefix	empty	Put in front of the user name and each group, like the API server’s --oidc-username-prefix and --oidc-groups-prefix
oidc_provider_name	from the issuer	The provider’s name on the sign-in button
oidc_clock_skew	30s	Allowed clock difference when checking token times
KUBEGLASS_TRUSTED_PROXIES	empty	Comma-separated CIDRs (or single addresses) of the proxies in front of KubeGlass. From these addresses KubeGlass believes X-Forwarded-For, for each client’s address in the rate limits, and X-Forwarded-Proto, to see the HTTPS a proxy ends and send HSTS. In impersonation mode it also believes X-Forwarded-User and X-Forwarded-Groups from them, and won’t start without the setting. Behind an ingress or load balancer, name it in every mode: otherwise every user counts as the proxy, in one rate limit, and KubeGlass logs a warning. In oidc and token modes it doesn’t make KubeGlass believe identity headers. An entry that is neither a CIDR nor an address stops KubeGlass at startup

Integrations

Setting	Default
prometheus_url	found in the cluster	Prometheus for metric history and PromQL on the cluster KubeGlass starts on. Without one, KubeGlass uses metrics-server. A cluster’s own Prometheus URL (Settings › Clusters, saved in <data dir>/config/clusters.json) comes first and applies at once
alertmanager_url	found in the cluster	Alertmanager for firing alerts and silences
alert_webhook_enabled, alert_webhook_url	off	Send drift findings to a webhook
alert_slack_enabled, alert_slack_webhook_url	off	Send drift findings to Slack
otel_enabled, otel_endpoint, otel_service_name, otel_sample_rate, otel_insecure	off, empty, kubeglass, 1.0, false	Export KubeGlass’s own traces over OTLP

KubeGlass looks for Prometheus and Alertmanager Services in the cluster (for example the ones kube-prometheus-stack installs) and reaches them through the API server’s service proxy, so no extra network access is needed.

Terminal

Setting	Default
enable_node_shell	false	Allow node shells. They start a privileged pod on the node. In the Helm chart, nodeShell.enabled
KUBEGLASS_NODE_SHELL_IMAGE	alpine:3.19, pinned by digest	Image for node shell pods. It needs nsenter and sleep
KUBEGLASS_INSTANCE_ID	empty	16 hex digits that name this KubeGlass on the node shell pods it makes, so at start it finds and deletes those it left behind. Empty uses one kept in the data directory. The Helm chart sets one per release
node_shell_namespace	kubeglass-system	Namespace for node shell pods, created if it doesn’t exist; KubeGlass doesn’t start with a name that isn’t a namespace’s. Its Pod Security level must allow privileged pods. Anyone who may create pods/exec in it can enter the node shell pods there, and through them the nodes, so grant that only to those who may have node shells
enable_local_shell	false	Offer a shell on the computer KubeGlass runs on in the dock (same as --local-shell). It turns on only with auth_mode local, outside a cluster and not in read-only mode; otherwise KubeGlass logs why and leaves it off. See Terminal
enable_tmux	false	Run shells on this computer in tmux, so closing the tab doesn’t end them. Without tmux installed, KubeGlass starts a plain shell
KUBEGLASS_MAX_TERMINALS	10	Terminal sessions per user
KUBEGLASS_MAX_GLOBAL_TERMINALS	100	Terminal sessions in total
KUBEGLASS_MAX_WS_CONNECTIONS, KUBEGLASS_MAX_WS_CONNECTIONS_PER_USER	512, 64	WebSocket connections in total and per user. A page keeps a socket open for each live list, so an application’s page holds about a dozen

Tuning

Setting	Default
kube_qps, kube_burst	100, 200	Request rate to each API server
list_all_timeout	15s	Limit for cluster-wide lists
rate_limit, rate_burst	100, 200	Requests per second per client to KubeGlass. The web UI’s files under /assets/ don’t count. Behind a proxy, the client is known only from a proxy in KUBEGLASS_TRUSTED_PROXIES
max_request_body_size, max_dynamic_body_size	1 MiB, 5 MiB	Request body limits; the second applies to YAML applies. A file uploaded to a pod can be up to 256 MiB whatever they say
auth_cache_ttl, auth_cache_max	1m, 10000	Cache of validated OIDC bearer tokens: how long one is taken from it at most (never past the token’s exp, with oidc_clock_skew), and how many it holds
drift_result_retention, drift_prune_interval	720h, 1h	How long drift results are kept

Changing settings while it runs

Settings shows the server settings that can change without a restart: log_level, prometheus_url (after a restart), alertmanager_url and the four alert delivery settings. Changes are saved in the data directory.

On your machine every admin can change them. In a cluster every one is locked, so the deployment stays the source of truth, except the ones listed in KUBEGLASS_UI_CONFIGURABLE, comma-separated, which admins may change from the UI. A cluster’s own Prometheus URL under Settings › Clusters follows the same rule, through prometheus_url.