Kobi
Actions & Governance
The full action surface, RBAC enforcement, dry-run previews, the Kobi governance switches, and the audit trail behind every mutation.
On this page
KubeBolt does not only observe — it acts. Actions reach the cluster from a person — a UI action on a resource page, or a call with an API token — from a Kobi Copilot proposal a person approves in chat, and, on KubeBolt Cloud, from Kobi Autopilot. 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, StatefulSet or DaemonSet | POST …/rollback | Editor | propose_rollback_deployment (Deployments) |
| 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.
Every record names its source, decided by the server from who made the
request — a request can claim one with the X-KubeBolt-Action-Source header,
but the claim alone is not believed:
| Source | When |
|---|---|
ui | A person in a browser session |
api | A person’s API token |
copilot_proposal | A Kobi proposal executed from the person’s own session and their own conversation |
autopilot | Kobi Autopilot, calling with its service token |
A claim that wasn’t believed stays in the record as claimedSource. The same
actor names the write in the cluster: Kubernetes records the field manager
kubebolt for a person, kubebolt-kobi for a Copilot proposal and
kubebolt-autopilot for Autopilot in the object’s managedFields. A manager
name is what the write claims to be, not who made it: any client can write
with any field manager, and Kobi reads it that way. A Copilot
record links to the conversation that proposed it, an Autopilot record to its
run and incident, and an action that started from an insight keeps the
originating insight id, 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, before you can click
Execute. A dry run is never audited and never persists anything.
Governance switches
Two toggles bound what Kobi Copilot may execute. Both default to on, and both can be changed without a restart as Kobi actions and Destructive actions in Administration → AI (Kobi) → Configuration — on KubeBolt Cloud, Administration → AI & Autopilot → Kobi Copilot:
| 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 | Delete is withheld from the model, and the action endpoints reject a Kobi-proposed delete or scale-to-zero with a 403 that names the policy, not your role. Scale-to-zero shares the non-destructive scale tool, so it cannot be filtered out of the tool list. |
How to set them with Helm or Docker Compose is in Enabling Kobi.
These two switches govern Kobi Copilot’s proposals 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, and Autopilot has
its own controls (below). 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.
Kobi Autopilot’s actions
On KubeBolt Cloud, Autopilot executes through the same endpoints, with its own
service token, and its records carry the source autopilot. It has a smaller,
fixed surface than Copilot, and its own controls:
| Autopilot action | What it changes |
|---|---|
restart_deployment | Rolling restart of a Deployment |
scale_deployment | Replica count of a Deployment |
rollback_deployment | Roll a Deployment back to an earlier revision |
patch_deployment_resources | CPU/memory requests and limits of a workload |
patch_hpa | An HPA’s minReplicas / maxReplicas |
patch_probe | A workload’s readiness or liveness probe timings |
verify_pods_ready | Nothing — waits for the pods to be Ready (180 s by default) |
inform_only | Nothing — tells a person what to do, for a cause outside the cluster |
- Only the plan runs. A change executes only as an action of the run’s plan, on the same target, with the plan’s arguments.
- What Autopilot reads is evidence, never policy. Text in annotations, labels, env, logs, cloud tags or External Secrets objects can’t make it stand down, defer or scale to zero: such a claim is recorded as unverified and the remedy is chosen as if it weren’t there. Only KubeBolt’s settings decide whether to act, which action, the approval and the cooldown, and scaling to zero is never treated as a repair.
- An investigation that asks for a person gates the plan. Every action that changes something then waits for approval, whatever the mode and the risk. The approval (the web card, the queue, Slack, the approval email and webhooks) says when its reason cites the workload’s own text.
- Approval follows the operating mode. In Approve & execute every change waits for a person; in Autonomous rollbacks, scale-to-zero, larger scale changes and riskier resource patches still wait. Approving or rejecting takes the Editor role, and an approval nobody answers in 5 minutes (the default) counts as rejected. Changing Autopilot’s settings takes Admin.
- Protected namespaces. The platform’s list (
kube-system,kube-publicandkube-node-leaseby default) plus any your organization adds: Autopilot never opens an incident or changes a workload there. - Revert on failed verification. When the pods don’t become Ready after a change, Autopilot reverts it — automatically in Autonomous, after an approval in Approve & execute.
The modes and the incident pipeline are in Meet Kobi; the settings are in KubeBolt Cloud.
Audit trail
Every mutation is persisted with the operator’s identity and role, the action source, the parameters applied, and the result. Admin changes — settings, connectors, clusters, insight policies, integrations — are recorded the same way, without their request bodies. The trail is read through the API — there is no audit page in the 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). Since 2.7.0 the class applies before the limit, so a filtered
page fills up to it; a record written before records carried a class reads as
a mutation. Records are pruned after KUBEBOLT_AUDIT_RETENTION_HORIZON
(default 2160h, 90 days).
Each record names the cluster it acted on: the one the request resolved for
mutations and the cluster-scoped integration routes (since 2.6.7), and the one
the access reached for terminals, port-forwards and file reads (since 2.6.4).
Records written earlier may carry the install’s default cluster instead. A
set-env record keeps the names and sources of the variables it changed, never
their values, in the trail and in the API log; older records are cleaned at
startup.
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. Cloud connector calls areaccessrecords too (mcp_tool_call), and since 2.7.0 they name the operation even when the call was blocked, held back by the per-minute budget or failed at the provider.
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 the permissions of the credentials it connects with (a kubeconfig, its own ServiceAccount, or the agent’s), and Connecting Clusters for the agent’s three permission tiers.