Actions & Governance
The full action surface, RBAC enforcement, dry-run previews, the Kobi governance switches, and the audit trail behind every mutation.
KubeBolt does not only observe — it acts. Actions reach the cluster from two origins: a UI action on a resource page, or a Kobi proposal you approve in chat. Every one of them is RBAC-enforced, most can be previewed before they run, and all of them are recorded in the audit trail. This page covers the action surface and the controls around it.
The action surface
The API and the UI ship more actions than Kobi can propose. Kobi’s propose_*
tools are a curated subset — the nine changes that are useful to reason about
in a conversation.
| Action | Endpoint | Role | Kobi can propose |
|---|---|---|---|
| Rolling restart | POST …/restart | Editor | propose_restart_workload |
| Scale replicas | POST …/scale | Editor | propose_scale_workload |
| Roll back a Deployment | POST …/rollback | Editor | propose_rollback_deployment |
| Set container image | POST …/set-image | Editor | propose_set_image |
| Set requests / limits | POST …/set-resources | Editor | propose_set_resources |
| Set environment variables | POST …/set-env | Editor | propose_set_env |
| HPA min/max replicas | POST /resources/hpas/…/set-bounds | Editor | propose_patch_hpa |
| Ephemeral debug container | POST …/debug | Editor | propose_debug_pod |
| Delete a resource | DELETE /resources/{type}/{ns}/{name} | Admin | propose_delete_resource |
| Apply edited YAML | PUT …/yaml | Editor | — |
| Create from a manifest | POST /resources/{type}/{ns} | Editor | — |
| Edit labels and annotations | POST …/edit-metadata | Editor | — |
| Reveal a Secret value | POST /resources/secrets/…/reveal | Editor, Admin in production namespaces | — |
| Cordon / uncordon a node | POST …/cordon · …/uncordon | Editor | — |
| Evict a pod | POST …/evict | Editor | — |
| Pause / resume a rollout | POST …/rollout-pause · …/rollout-resume | Editor | — |
| CronJob suspend / resume / trigger | POST …/suspend · …/resume · …/trigger | Editor | — |
| Drain a node | POST …/drain (GET tracks, DELETE cancels) | Admin | — |
| Open a port-forward | POST /portforward | Editor | — |
Drain sits with delete at Admin because evicting every pod on a node can
violate PodDisruptionBudgets and degrade cluster capacity. Cordon and uncordon
stay at Editor — they only flip a scheduling flag. A single-pod evict is Editor
too: it goes through the policy/v1 Eviction API, so a PDB that would be
violated returns 429 instead of a disruption.
The origin is stamped on every record via the X-KubeBolt-Action-Source header:
ui by default, copilot_proposal when you approved it in chat. An action that
started from an insight keeps the originating insight id on the Kobi
conversation, so the audit trail can be walked from symptom to fix.
Dry-run preview
Every action Kobi can propose accepts ?dryRun=true — restart, scale,
rollback, set-image, set-resources, set-env, set-bounds, debug, and delete. The
dry run goes through full admission (dryRun=All), so quota violations,
LimitRanges and admission webhooks surface before you approve, with the quota
detail parsed out of the apiserver’s error rather than shown raw. Kobi’s action
card runs that preview automatically for every proposal except rollback, which
the card executes without a preview.
Governance switches
Two toggles bound what Kobi may execute. Both default to on, and both can be changed in Administration → AI (Kobi) → Configuration without a restart:
| Env var | Default | Effect when off |
|---|---|---|
KUBEBOLT_AI_ACTIONS_ENABLED | true | The propose_* tools are withheld from the model entirely. Kobi still diagnoses and recommends, and offers the equivalent kubectl command instead. |
KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLED | true | Destructive verbs are withheld from the model and rejected server-side. This also catches scale-to-zero, which shares the non-destructive scale tool and so cannot be filtered out of the tool list. |
These two switches govern Kobi-proposed actions only — the server-side
gate matches on X-KubeBolt-Action-Source: copilot_proposal. A UI action from
a resource page is governed by RBAC, not by these toggles. Turning
KUBEBOLT_AI_ACTIONS_ENABLED off makes Kobi advisory; it does not make the
install read-only. For that, give people the Viewer role.
Together they let you match the blast radius to the environment: full proposal and execution in dev, diagnosis only in production, for example.
Audit trail
Every mutation is persisted with the operator’s identity, the action source, the parameters applied, and the result. The trail is read through the API — there is no audit page in the open-source UI:
curl -H "Authorization: Bearer $TOKEN" \
"https://kubebolt.example.com/api/v1/admin/actions?class=mutation&limit=200"GET /api/v1/admin/actions is admin only and returns the newest records first.
class is mutation, access or all (the default); limit defaults to 100
(maximum 1000). Records are pruned after KUBEBOLT_AUDIT_RETENTION_HORIZON
(default 2160h, 90 days).
Two action types carry extra audit weight:
- Secret reveal emits a second record on a dedicated channel carrying the written reason, the keys requested, and the outcome — including denied attempts. Neither record ever contains a value. See Resource Views.
- Access sessions — pod terminals, port-forwards and pod file reads and
downloads — are recorded with class
access, notmutation: an open/close pair with what was reached, paths, sizes and durations. The content crossing them is never recorded.
Actions always run under the detected RBAC permissions — Kobi can never do more than the cluster grants. See RBAC for how KubeBolt detects and adapts to your kubeconfig’s permissions, and Connecting Clusters for the agent’s three permission tiers.