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 (admins only) 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. Every AI feature (the Copilot, Diagnose, alert investigation, YAML assist) obeys both settings:
| Setting | Behavior |
|---|---|
| Allowed Providers | Multiselect from the 7 supported providers: Anthropic, OpenAI, Google Gemini, Azure OpenAI, Groq, Ollama, Custom. Default: all ticked. A provider that is not ticked is refused with HTTP 403 before any request leaves the cluster, whether or not Local Only is on. A list with nothing ticked restricts nothing; to stop all AI use, turn AI off with the master switch instead. |
| Local Only (off by default) | Additionally refuses every provider you do not host yourself. Only Ollama and a Custom OpenAI-compatible endpoint remain available, and only if Allowed Providers also permits them. |
A refused request returns an error naming the provider and what is allowed.
For full data residency (no cluster data leaving your network), turn Local Only on and tick only Ollama, or a Custom endpoint you run inside your network. Where a Custom endpoint may point is governed by Egress Control below.
Upgrading from 1.3.1 or earlier
Up to 1.3.1 the allow-list was consulted only when Local Only was also on, so a provider you had unticked kept receiving requests. It is now enforced on its own. If you unticked a provider you still use, tick it again before upgrading, or its AI requests will be refused. Local Only now also refuses cloud providers that are ticked.
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¶
Daily budgets on token usage and API request counts: one across all providers together, and one per provider. Usage is checked before every request to a provider, including each step of a multi-step Copilot conversation. With Hard Stop on, a reached budget refuses further AI requests with HTTP 429.
| Setting | Description |
|---|---|
| Enabled | Off by default. When on, usage is counted against the budgets below. |
| Hard Stop | Off by default. On: a reached budget blocks further calls. Off: the budgets only count. |
Daily token limit (daily_token_limit) |
Tokens per day across all providers together. Set to 0 for unlimited. |
Alert threshold (alert_threshold_pct) |
Share of the daily token limit at which KubeManta raises one warning a day, whether or not Hard Stop is on. Default 80%. |
| 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.
Treat cost caps as a spend guard rather than a hard ceiling: if the usage record cannot be read, the check lets the request through rather than walling AI off on a bookkeeping error. The hard ceiling is the spending limit on the provider key itself.
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 recognises 17 families of credential shapes (cloud keys, bearer and API tokens, private keys, connection strings, password=-style assignments and more). Measured against a 110-case corpus it catches about 90% of secrets that appear whole in one log chunk; a secret split across two log lines or two stream chunks is usually still missed. Treat it as best-effort defence in depth, not a guarantee, and add custom patterns for any org-specific secrets or PII.
Prompt injection: what is and is not protected¶
Anyone who can write text the AI reads — a log line, an event, an annotation, a container name or image tag — can try to give the AI instructions. There is no complete defence against prompt injection in any AI product today; the layers below reduce the risk, they do not eliminate it.
- Labelled cluster text. Tool results, attached files, the YAML in the editor and alert messages reach the AI inside markers that identify them as untrusted data, with standing instructions never to follow text inside them. Cluster text cannot close a marker early — any copy of the marker is removed first. Results served to external agents over MCP carry the same markers.
- Held sensitive reads. A read you did not name yourself in the conversation is held when it is: the full contents of a ConfigMap or anything Secret-shaped; raw logs or YAML from a namespace other than the one you are working in; or a report delivered to an email address or webhook you did not type. An admin gets an approval card (each approval is audited); a viewer, and the automated alert investigation, get a refusal the AI explains.
- Hard bounds, independent of the AI. Write approval, namespace scope, secret redaction, the egress allowlist and the air-gapped deployment mode (with a local model) all apply whatever the AI has been persuaded of.
Residual risk: injected text can still shape the wording of an answer, and the held-read check compares names literally rather than judging intent. Treat an approval card for a read you did not expect as a warning sign.
Where settings live¶
Guardrails are persisted in the agent's database rather than in a config file, so a change takes effect without a redeploy. 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.
If the stored guardrails cannot be read, AI is refused (HTTP 503, "the AI guardrail configuration could not be read") rather than run without your policy. A configuration read successfully within the last five minutes stands in for a brief read failure, so one transient error does not take AI down; after that, AI stays off until the configuration can be read again.
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.