Kuboard System Settings
This page is for administrators. It covers system-level configuration: where each setting is changed, what its default value is, and how the change takes effect.
How to Open
Entry: left menu → Settings → System Settings. The page lists all configuration as tabs on the left side. Saving changes on the page requires administrator privileges.
| Interface tab (Settings → System Settings) | Configures | Notes |
|---|---|---|
| Log Parameter Settings | Log levels | Normal / lowest / sync-task log levels |
| JWT Token | Login token secret | Only offers a "Regenerate" button |
| Cluster Cache Settings | Cluster sync and resource cache | Sync thread pool + cache method per resource |
| User Login Settings | Login, password, MFA, OIDC | The most complex; split across multiple cards |
| Audit Policy Settings | Audit switch and rules | Three rule scopes: Kuboard / cluster / namespace |
| Interface Settings | Site and terminal theme | Title, icon, footer, GA |
| Node Shell | Node debug Pod | Image, namespace, session duration |
| Menu Item Settings | Disablable resources and menu items | Tree checkboxes; refresh the menu after saving |
| MCP Server | MCP service and Prometheus tools | Switch, rate limit, approval |
Configuration Overview
| Configuration category | Default value | How it takes effect after saving |
|---|---|---|
| Login sessions | Session 30 minutes; multi-window login off; MFA off; OIDC off | Immediately (applies to new sessions) |
| Password policy | 6–24 characters including uppercase, lowercase, and digits; lock for 60 minutes after 5 failures | Immediately |
| JWT Token | Generated automatically at first install | After regeneration all users are forced to log in again |
| OIDC encryption key | Generated automatically at first start (no UI) | After rotation, historical ciphertext cannot be decrypted |
| Audit | Recorded to database; file logging off; retained 6 months | Immediately |
| Cluster cache sync | Thread pool 10/200; about 32 resources via watch/polling | Immediately |
| System cache | Internal cache, no UI | — |
| Menu and resources | 21 K8s resources disabled by default | Immediately (after refreshing the menu) |
| MCP Server | Master switch off; approval for write operations on; Prometheus tools on | Immediately; per-user SSE subscription cap requires a restart |
| Site interface | Title Kuboard; GA on | Refresh the page after saving |
| Log levels | Normal INFO; lowest TRACE; sync-task INFO | Immediately |
| Node Shell | Image netshoot; namespace kube-system; TTL 3600 seconds | Applies to new sessions |
How changes take effect differs
After saving, most configuration takes effect immediately (the server clears the corresponding configuration cache). The only exceptions:
- Interface Settings: refresh the browser page after saving to see the new title / icon / terminal theme;
- JWT Token regeneration: all online users are forcibly logged out and must sign in again;
- Per-user MCP SSE subscription cap: restart the Kuboard service after saving;
- Log levels: effective immediately without a restart, but log lines already written do not change.
Login and Authentication
Entry: Settings → System Settings → User Login Settings, shown as cards "General Settings / Password Policy / MFA Settings / OIDC SSO / External User Repository".
General Settings and Sessions
| Setting | Default | Description |
|---|---|---|
| Session timeout (minutes) | 30 | Applies to sessions established afterwards; re-login required after timeout |
| Allow multi-window login | Off | When off, logging in again with the same account kicks the previous session; when on, multiple browsers / tabs can stay online at once |
Password Policy
| Setting | Default | Description |
|---|---|---|
| Password length | 6–24 characters | Validated when creating and changing passwords |
| Character mix | Uppercase / lowercase / digits on, special characters off | Combination requirement |
| Initial password validity (days) | 3 | When creating a user or resetting a password, expiry is set to N days later |
| Validity after changing password (days) | 90 | Validity of a password changed by the user themselves |
| Lock after failed attempts | Lock for 60 minutes after 5 failures | Account locked once the limit is reached |
| No reuse of recent passwords | 3 | New password must differ from the last N passwords |
MFA (Multi-Factor Authentication)
| Setting | Default | Description |
|---|---|---|
| Enable MFA | Off | When on, a second TOTP one-time-password verification is added |
| Force binding | Off | When on, users must complete binding before they can log in |
| Enable recovery codes | On | Allows generating recovery codes, so a lost device does not lock you out |
OIDC SSO
The "OIDC SSO" card configures a single IdP. Turn on Enable OIDC Login and fill in:
- Connection: Backend Issuer URI, Browser-Facing Issuer URI, Allowed Frontend Origins (required), Client ID, Client Secret, Scopes, Login Button Label;
- Claims mapping: Username / Email / Full Name claim, Trust IdP Email (merge accounts);
- OIDC MFA: Trust IdP MFA, Enforce MFA, ACR Values for MFA, Auth Time Max Age (seconds);
- Silent renewal: Enable Silent Renewal, Silent Renewal Threshold (seconds);
- IdP-initiated logout: once enabled, a Single Logout URL appears — paste it into the IdP.
Once enabled, the card shows a "Before you save, complete these 3 steps" guide (register the callback URL → fill both issuer URIs → save and run the self-check). The whitelist offers Use current address and shows in real time whether the current address is whitelisted. Changes take effect immediately after saving. Start check uses the saved configuration to fetch the IdP discovery document once and verify everything element by element.
Full configuration notes, self-check findings and default values are in OIDC Single Sign-On.
External User Repository (Webhook)
| Setting | Default | Description |
|---|---|---|
| Enable external user Webhook | Off | When on, username / password are validated by an external Webhook service |
| External user Webhook URL | Empty | Required when enabled |
JWT Token
Entry: Settings → System Settings → JWT Token. This shows the JWT public/private keys (read-only; the private key is redacted), and the only operation is Regenerate. After regeneration all logged-in users are forcibly logged out. When multiple instances share the same database, keep the key consistent; regular rotation is generally unnecessary.
Audit
Entry: Settings → System Settings → Audit Policy Settings. The audit log only records operations performed through the Kuboard UI or the Kuboard API; it does not cover external K8s management tools such as kubectl.
Log Persistence
| Setting | Default | Description |
|---|---|---|
| Record to database | On | Auto-cleaned by retention period |
| Record to file | Off | Written to the log directory inside the container |
| Retention period (months) | 6 | Database logs only; 0 means never auto-deleted |
| Max request body length | 4096 | File logs only; excess is not recorded |
| Max response body length | 4096 | File logs only |
Audit Rules
Audit rules are maintained separately for the three scopes Kuboard / cluster / namespace. A rule contains:
| Dimension | Values | Description |
|---|---|---|
| Action | Record / Don't record | The action taken when a rule matches; later rules are ignored |
| Resource | e.g. deployments, pods/exec; * means all | Resource name; an API group (e.g. apps) can be scoped |
| Verb | get / list / create / update / delete | Operation verb |
| Scope | cluster: clusters; namespace: the matching cluster + namespaces | Limits the scope of the rule |
Rules are matched top-down, one by one; the first matching rule wins. If no rule matches, the default action is record. Rule cards can be reordered by drag-and-drop, and the whole rule set can be exported / imported (JSON).
Default rules on a fresh install (editable in the UI):
- Kuboard scope: read operations not recorded; login-token refresh not recorded; MCP subsystem reads not recorded, writes recorded;
- Cluster scope: read operations not recorded;
- Namespace scope: exec (enter container) recorded, other read operations not recorded.
Cluster Sync and Resource Cache
Entry: Settings → System Settings → Cluster Cache Settings. Kuboard syncs commonly used cluster resources into a local cache; the UI and API read from this cache to improve response speed.
Sync Parameters
| Setting | Default | Description |
|---|---|---|
| Core threads | 10 | Resident threads of the sync thread pool |
| Max threads | 200 | Peak concurrency ceiling; not below the core count |
| Full sync task timeout (minutes) | 5 | A task not finished in time is restarted |
| Full sync retry interval (minutes) | 1 | Minimum delay for failed tasks |
| Retry validity (minutes) | 30 | No further retries after this period |
| Incremental listen cycle (seconds) | 300 | Watch connection rebuilt after timeout |
| Reset unfinished incremental task (minutes) | 10 | If an incremental task is stuck beyond this, restart a full sync |
| Full sync max pages | 0 (unlimited) | Page-count guardrail for a single paging round; when hit with data still remaining it is treated as a failure, never a silent truncation of the cache |
| Consecutive no-progress page threshold | 3 | How many pages in a row without new data count as a paging anomaly |
| Restart full sync after N minutes without progress | 10 | A slow-but-progressing cluster is not interrupted repeatedly |
| Watch resync timeout (seconds) | 1800 | The longest time allowed to fetch all existing objects |
Cache Object Settings
| Dimension | Description |
|---|---|
| Resource key | e.g. apps / deployments |
| Sync method | Real-time watch (push) or polling (pull at an interval) |
| Poll interval (minutes) | Only needed for polling |
| Delayed deletion (hours) | Only for events resources: kept locally for extra time after deletion on the K8s side (7 days by default) |
A fresh install caches about 32 resources by default: Pod, Deployment, StatefulSet, DaemonSet, etc. are watched in real time; Service, ConfigMap, Secret, Ingress, RBAC, etc. are polled every 5 minutes; admission webhook configurations, FlowControl, RuntimeClass, etc. are polled every 300 minutes; DRA (Dynamic Resource Allocation) resources are watched in real time.
Menu and Resource Enable/Disable
Entry: Settings → System Settings → Menu Item Settings. The page shows the Kuboard menu and all K8s resources as a tree: checked means enabled (visible in the UI), unchecked means disabled (hidden from the menu). Resources marked "core" cannot be disabled; the menu cache is cleared as soon as you save, so refresh the page to see the effect; the search box filters by title / path.
On a fresh install, 21 uncommon K8s resources are disabled by default, including RuntimeClass, VolumeSnapshot (snapshots), CSI-related items, admission webhook configurations, FlowControl, Lease, PriorityClass, PodDisruptionBudget, EndpointSlice, and DRA-related resources.
MCP Server
Entry: Settings → System Settings → MCP Server. MCP Server exposes Kuboard capabilities (K8s read/write, Prometheus queries, change-plan approval, etc.) to AI clients as MCP (Model Context Protocol) tools, at the endpoint <Kuboard access URL>/mcp.
| Setting | Default | Description |
|---|---|---|
| Enable MCP Server | Off | When off, /mcp returns 404 |
| Force approval for Agent write operations | On | Writes are first dry-run and staged as a plan, then executed after manual approval in the UI; when off they execute immediately — keep on in production |
| Auto-continue after approval | On | The approval result is returned to the agent together with the one-time token, and the agent continues on its own; when off the token is not returned and must be copied from the UI by hand |
| CORS allowed Origins | Empty (all cross-origin rejected) | Browser-side cross-origin allowlist, exact Origin match |
| Max bytes per request body | 10MB | Requests over this are rejected |
| Per-user rate limit | 50 per 60 seconds | Sliding window; returns HTTP 429 when exceeded |
| Max SSE subscriptions per user | 100 | Requires a service restart after saving |
Prometheus Tools
| Setting | Default | Description |
|---|---|---|
| Enable Prometheus tools | On | When off, calls return "no service found" |
| Max series per instant query | 10000 | Prevents large queries from overwhelming Prometheus |
| Max points per range query | 100000 | series × time points |
| Query timeout (seconds) | 30 | Prometheus HTTP query timeout |
| Per-query RBAC authorization | On | Each query resource is permission-checked individually |
| Aggregation query policy | Allowed with per-dimension authorization | Alternatives: "deny aggregation" and "cluster-scope only" |
| Aggregation query rate-limit multiplier | 5× | Rate limit as a multiple of the normal query limit |
| Max dimension expansion for aggregation | 100 | Max namespace / node dimensions expanded per aggregation |
| Per-cluster service discovery | Empty | Overrides service-discovery rules per cluster |
Site Interface
Entry: Settings → System Settings → Interface Settings. After saving site info, refresh the browser page to see the new title, icon, and footer.
| Setting | Default | Description |
|---|---|---|
| Page title / product name | Kuboard / Kubernetes multi-cluster management | Shown on the login page and browser tab |
| Footer text | Official site domain by default | Can be changed to your own site domain |
| System icon | Built-in icon | Upload JPG/PNG (≤50KB) |
| Default palette | Deep Blue | Switches the primary color together with the success / warning / danger / info colors as one set; users can pick their own in Theme Settings in the header |
| Google Analytics | Enabled | Collects anonymous usage data; no sensitive cluster data |
| Terminal font size / line spacing | 14 / 1.2 | Terminal display |
| Terminal theme type / name | dark / AtelierSulphurpool | Applies to new terminal sessions opened afterwards |
| Terminal log lines | 500 | Max log lines echoed in the terminal |
Color Palette
A "palette" defines the primary color together with the success / warning / danger / info colors as one set. Those colors are what actually appear together in the interface — letting users pick only a primary color while the semantic colors stay fixed would push the job of matching colors onto the user, and the tones end up clashing. Switching a palette switches the whole set.
Six presets are built in: Deep Blue (default), Slate, Teal, Amber, Indigo, Forest.
Precedence: the user's own choice > the site default > the built-in default.
- Site default: Settings → System Settings → Interface Settings → Default palette, applied to every user who has not picked one;
- User's own choice: Header → Theme Settings → Color Palette, affecting only the current user and leaving the site default unchanged.
Colors change, layout does not
A palette only covers the chromatic colors (the primary color and the four semantic colors). Neutral colors — background, borders, text — are shared across the site, so switching palettes never changes the layout or the readability baseline.
Log Levels
Entry: Settings → System Settings → Log Parameter Settings. Takes effect immediately on save, no restart needed.
| Setting | Default | Description |
|---|---|---|
| Normal log level | INFO | Level for normal requests |
| Lowest log level | TRACE | The lowest allowed level; usually for temporary troubleshooting |
| Sync-task log level | INFO | Cluster cache sync tasks; ERROR is recommended in the UI to avoid log flooding |
| Error stack trace to console | On | Exception stack printed to stdout |
| Error stack trace in response | Off | Returned to the client; for debugging only |
Node Shell
Entry: Settings → System Settings → Node Shell. Node Shell creates a privileged debug Pod on the target node and accesses the node's filesystem, processes, and network namespace through a container terminal. The following parameters apply globally:
| Setting | Default | Description |
|---|---|---|
| Image | nicolaka/netshoot | Image used to create the debug Pod |
| Start command | sleep infinity | Keeps the container alive so you can enter it |
| Namespace | kube-system | Where the debug Pod is created (must exist and be permitted) |
| Session duration (seconds) | 3600 | Session expires after the timeout; the Pod is cleaned up automatically |
| Resource limits | Requests 100m CPU / 128Mi memory; limits 500m CPU / 512Mi memory | Resource requests and caps for the debug Pod |
Settings Without UI
| Setting | Description |
|---|---|
| System cache | Internal in-memory cache (Caffeine); default capacity 50–500 entries, expiry 5–30 minutes; not configurable in the UI — keep the defaults |
| OIDC encryption key | Generated automatically at first start; used to encrypt IdP clientSecret and tokens. Back it up from the database before enabling OIDC; rotation makes historical ciphertext undecryptable |
Related Pages
- User Login (session timeout, multi-window login, external user repository)
- Password Policy and Changing Passwords
- MFA Multi-Factor Authentication
- OIDC Single Sign-On
- Disabling Menu Items
- MCP Server
