AI Guardrails¶
KubeManta's AI Guardrails let administrators set org-wide AI policy — independent of per-user model/key settings. Configuration is in Admin → AI Guardrails (admin password required) and persists across pod restarts.
Master AI switch¶
AI Enabled (on by default) — turning this off:
- Blocks every AI entrypoint: diagnosis, autonomous investigation, AI YAML assist, MCP AI tools
- Returns HTTP 403
{"error": "AI is disabled by the administrator"}on any attempt - Hides AI surfaces in the UI (Diagnose panel, AI nav, analysis buttons)
- The terminal, workloads, overview, and all non-AI features continue working
This is the enterprise "AI off" control for compliance environments where LLM calls must be prohibited.
Data residency¶
Control which LLM providers are allowed to receive cluster data:
| Setting | Behavior |
|---|---|
| Local Only (off by default) | When enabled, only providers in the allowlist are permitted. Any request to an unlisted provider is rejected with HTTP 403 before any API call is made. |
| Allowed Providers | Multiselect from the 7 supported providers: Anthropic, OpenAI, Google Gemini, Azure OpenAI, Groq, Ollama, Custom. Default: all allowed. |
For full data residency (no cluster data leaving your network), set Local Only = on and restrict the allowlist to Ollama.
Write safety¶
| Control | Default | Description |
|---|---|---|
| AI Read-Only Kill Switch | Off | When on, blocks ALL AI write tools (delete pod, restart deployment, scale). AI can still read and diagnose — only mutations are blocked. |
| Require Approval for All | On | Every AI write pauses for human approval in the UI, even in Auto mode. |
| Blast Radius Limit | 5 operations | Hard cap on write operations per session. Sessions that hit this limit block further writes for that session. |
| Blast Window | 3600 seconds | Window for the per-session write count. |
| Circuit Breaker Threshold | 3 failures | Number of consecutive write-tool failures before the circuit breaker trips and blocks all writes. |
| Circuit Breaker Reset | 300 seconds | Time before the circuit breaker auto-resets. |
Circuit breaker state and blast-radius counts are persisted in SQLite, so they survive pod restarts — a crash cannot reset safety limits.
Cost caps¶
Per-provider daily budgets on token usage and API request counts. When a budget is exceeded, the AI entrypoint returns HTTP 429 (fail-closed — no partial requests).
| Setting | Description |
|---|---|
| Enabled | Off by default. When on, checks budget before every AI call. |
| Hard Stop | If on (default when enabled), exceeding the budget blocks the call. |
| Per-provider daily token limit | Set to 0 for unlimited. Today's usage is shown as a progress bar next to each provider. |
| Per-provider daily request limit | Set to 0 for unlimited. |
Token counting is best-effort: providers that return usage metadata (Anthropic, OpenAI) use the exact count; others use an estimate of chars/4.
Namespace scope¶
Restrict which namespaces the AI can read from or write to:
| Mode | Behavior |
|---|---|
| All (default) | AI can access any non-blocked namespace. |
| Allow | AI can only access namespaces in the allowlist. |
| Deny | AI is blocked from namespaces in the denylist. |
Requests targeting out-of-scope namespaces are blocked and audited.
Strict cluster scope (on by default) appends a hard "stay inside Kubernetes/KubeManta, refuse off-topic questions, never fetch external URLs" block to the copilot, generic, and Helm-values system prompts. This is best-effort LLM refusal — the real boundary is the egress allowlist and the write-approval gate below.
Egress Control¶
A deny-by-default allowlist of the outbound hosts the AI path may reach — the hard boundary that backs the data-residency and scope controls above. It governs the AI provider base_url / Ollama URL on every AI call (both chat loops and autonomous alert investigation).
| Setting | Behavior |
|---|---|
| Enabled | false (default) = allow-all (back-compat). When on, an outbound AI host must match an allowlist entry, a *.suffix wildcard, a known provider host (if auto-allow is on), or be a private-IP literal — otherwise the call is blocked. |
| Allowed domains | Exact hosts or *.suffix wildcards. Seeded by KUBEMANTA_AI_EGRESS_DOMAINS (csv). |
| Auto-allow provider endpoints | Treat the configured provider's own host as allowed without listing it explicitly. |
Blocked attempts are audited (egress_blocked in the audit log + Activity feed). Egress control is fail-safe on a config error. Non-AI outbound traffic (alert webhooks, license checks, SSO metadata) is explicitly out of scope.
Enforcement is always on; configuring it is Enterprise
Enforcement of an already-configured egress allowlist runs on every install and every tier — a set policy is always honored. Only editing the egress section requires an Enterprise license (ai_governance). A Pro admin editing cost caps, scope, or write safety is never blocked; only a change to the egress section itself calls the feature gate.
Env seeds: KUBEMANTA_AI_EGRESS_ENABLED, KUBEMANTA_AI_EGRESS_DOMAINS.
For the full list of AI provider domains to allow at your network edge, see Install → Network access.
Compliance¶
| Control | Default | Description |
|---|---|---|
| Prompt Audit | Off | When on, each AI prompt and response (scrubbed) is written to an internal log with actor, model, namespace, and timestamp. |
| Prompt Retention | 30 days | Log entries older than this are pruned on insert. |
| Redaction | On | Scrubs known secret patterns (API keys, tokens, passwords) from prompts before they reach the LLM. |
| Custom Redaction Patterns | [] |
Additional regex patterns to scrub. Validated server-side on save — malformed patterns are rejected. |
The default redaction pass covers common secret formats (AWS keys, Bearer tokens, password= patterns, etc.). Add custom patterns for any org-specific secrets or PII.
Where settings live¶
Guardrails are persisted in the kubemanta_settings SQLite table under the key ai_guardrails. They are loaded at agent startup and cached; the cache is busted on every save. Environment variables (KUBEMANTA_AI_LOCAL_ONLY, BLAST_RADIUS_LIMIT, etc.) set the initial defaults on first startup and are overridden by the stored config thereafter.
API¶
For automation:
# Read current config
curl -s http://kubemanta-agent:8080/admin/ai-guardrails \
-H "Cookie: km_session=<session-token>"
# Update (full config body required)
curl -s -X PUT http://kubemanta-agent:8080/admin/ai-guardrails \
-H "Content-Type: application/json" \
-H "Cookie: km_session=<session-token>" \
-d '{"ai_enabled": false}'
Both endpoints are admin-gated.