Configuration
RBAC & Permissions
What KubeBolt may do in your cluster: the credentials it uses, the ClusterRole the chart creates, how it probes its permissions, and how the UI degrades when they are narrow.
On this page
This page is about what KubeBolt may do in the cluster. What each KubeBolt user may do in KubeBolt — the Viewer, Editor and Admin roles — is covered in Authentication. An action needs both: a role that allows it and cluster permissions that allow it.
KubeBolt never impersonates the signed-in user. Every read and every action runs with KubeBolt’s own Kubernetes credentials, so those credentials are the ceiling for everyone — Kobi included.
Which credentials KubeBolt uses
| Connection | Credentials | Where the scope is set |
|---|---|---|
| In-cluster (the Helm chart) | The chart’s ServiceAccount | The chart’s ClusterRole — below |
| Kubeconfig context (on disk or uploaded in the UI) | Whatever user the context carries | Your kubeconfig and the cluster’s RBAC |
| Agent-connected | The agent’s ServiceAccount | The agent chart’s rbac.mode — below |
On KubeBolt Cloud every cluster is agent-connected.
The chart’s ClusterRole
With rbac.create=true (the default), the kubebolt chart binds a ClusterRole
to its ServiceAccount. It grants:
| Grant | Why |
|---|---|
get / list / watch on core, apps, batch, networking, policy, autoscaling, storage, RBAC, discovery and Gateway API resources, plus optional CRDs (cert-manager, Argo CD, VPA, Cilium, External Secrets, Trivy, Kyverno policy reports) | Inventory, topology, insights, the Security dashboard |
get / list on metrics.k8s.io pods and nodes | Live CPU and memory from Metrics Server |
create on selfsubjectaccessreviews | The permission probe below |
create on pods/exec, pods/portforward, pods/eviction | Terminal, file browser, port-forward, evict |
create / update / delete on workloads, Jobs, CronJobs, Pods, Services, PVCs, NetworkPolicies, Ingresses, HPAs, StorageClasses and Gateway API objects (plus patch on workloads, Jobs, CronJobs, HPAs and Gateway API objects); get / update on deployments/scale and statefulsets/scale | Edit YAML, create from a manifest, restart, scale, delete |
create / update / delete on Secrets, ConfigMaps, ServiceAccounts, RBAC objects; create on Namespaces and DaemonSets; escalate / bind on Roles and ClusterRoles | The first-boot admin-password Secret, agent ingest-token Secrets, and the agent install wizard |
create on tokenreviews | Only with agentIngest.rbac.enableTokenReview=true (default): agents that authenticate with their projected ServiceAccount token |
The role grants no writes on Nodes and no patch on core kinds such as
Services, ConfigMaps and Secrets. On the cluster KubeBolt runs in, cordon,
uncordon and drain, and label or annotation edits on those kinds, come back
403 unless you bind an extra ClusterRole to the chart’s ServiceAccount that
grants them.
To run KubeBolt with less, set rbac.create=false and bind your own ClusterRole
(or Roles) to the chart’s ServiceAccount — named after the release by default
(kubebolt for a release called kubebolt), or whatever you set in
serviceAccount.name. A read-only role works: KubeBolt probes what
it was given, the UI degrades as described below, and write actions come back
403 from the apiserver. Keep create on selfsubjectaccessreviews, or the
probe cannot tell what you granted.
Permission Detection
KubeBolt probes its permissions when it connects to a cluster — any cluster, whichever credentials it uses:
- One
SelfSubjectAccessReviewfor thelistverb on each of 31 resource types, run on a dedicated client with at most 10 in flight. A probe takes a few seconds. - Two phases. Cluster-wide first. For every namespaced type that is denied
cluster-wide, KubeBolt then looks for RoleBinding-based access: it lists the
namespaces, keeps those where it may list Pods, and re-checks the denied
types there. Granted types get per-namespace informers instead of
cluster-wide ones. Since 2.6.5 a namespace list that fails is retried, and
if it keeps failing those types stay without access and the views say so,
rather than being served from a guessed set;
default,kube-systemandkube-publicare tried only when the credentials may not list namespaces at all. - Optional CRDs (cert-manager, Argo CD, VPA, Cilium policies) also have to be served by the cluster. A CRD that RBAC allows but the cluster doesn’t have reads as “not installed”, not as a restriction, and these are re-checked every 2 minutes, so installing one later needs no restart.
- Write access is one more review (
updateon Deployments). On agent-connected clusters it decides thereader/operatorbadge (modeinGET /api/v1/clusters) and is refreshed while connected. - If the
SelfSubjectAccessReviewAPI itself is unavailable, KubeBolt assumes full access and lets the apiserver refuse what it must.
The core probe runs once per connection. After you change RBAC, restart the KubeBolt API so it reconnects and probes again.
Access Levels
| Level | Backend | Frontend |
|---|---|---|
| Cluster-admin or full read | Informers start for every type | Full UI, no restrictions |
| Cluster-wide, some types denied | Informers for permitted types only | Restricted items dimmed, “Limited access” banner |
| Namespace-scoped (RoleBindings) | Per-namespace informer factories, results merged | Resources from the permitted namespaces only |
Frontend Behavior
- A dismissible amber Limited access banner counts the resource types RBAC restricts. Optional CRDs that aren’t installed don’t count; they get a separate, neutral notice.
- Sidebar items for restricted types are dimmed and carry a shield icon.
- Summary cards read “No access — insufficient permissions” instead of
0. - Without access to Nodes, capacity panels read “No access to Nodes — capacity data unavailable”.
- Opening a restricted resource list shows a permission-denied page; the API
answers
403(insufficient permissions to access <type>).
Troubleshooting walks through the banner on an agent-connected cluster.
The agent’s RBAC tiers
On agent-connected clusters you choose the agent’s
scope up front with --set rbac.mode= on the agent chart, and KubeBolt then
probes that scope like any other:
metrics— narrow ClusterRole: kubelet stats (nodes/stats,nodes/metrics,nodes/proxy), Podslist/watch, Nodeslist, Namespacesget. The agent ships metrics and Hubble flows and nothing else; no apiserver call traverses its tunnel, so the cluster is monitored-only — resource views answer503and the UI shows the metrics dashboards. Impliesproxy.enabled=false.reader(default) — cluster-wideget/list/watchon*/*. The backend reads inventory through the agent’s tunnel for a full read-only dashboard; write verbs come back403. Impliesproxy.enabled=true.operator— read and write on*/*, plus exec, port-forward and eviction: effectively cluster-admin scoped to the agent’s ServiceAccount. Required for exec, scale, restart, delete and YAML edits through the dashboard. The chart does not block it without agent authentication, but use it only withauth.modeother thandisabled: without auth, anyone who can reach the backend’s agent port gets cluster-admin in that cluster.
More on choosing a tier in Connecting clusters.
API Endpoint
GET /api/v1/cluster/permissions returns the probe result for the selected
cluster, keyed by resource type. Each entry carries resource, group,
canList, canWatch and canGet, plus namespaceScoped and namespaces
when access comes from RoleBindings, and absent for an optional CRD the
cluster doesn’t serve.
{
"pods": { "resource": "pods", "group": "", "canList": true, "canWatch": true, "canGet": true },
"nodes": { "resource": "nodes", "group": "", "canList": false, "canWatch": false, "canGet": false },
"argocdapps": { "resource": "applications", "group": "argoproj.io", "canList": false, "canWatch": false, "canGet": false, "absent": true }
}