The Kubernetes RBAC verbs
A verb in a Kubernetes Role or ClusterRole names an action on a resource. These are the verbs every built-in resource uses:
get: read one object by name.list: read every object of a kind, in a namespace or across the cluster.watch: stream changes to objects as they happen.create: make a new object.update: replace an existing object.patch: change part of an existing object.delete: remove one object.deletecollection: remove many objects in one request.
A few resources add their own verbs: bind, escalate, impersonate,
approve, sign and attest, covered below. * means every verb,
including ones Kubernetes adds later.
Verbs are case-sensitive. GET or Get in a role grants nothing, and Kubernetes doesn’t warn
you: it accepts any verb name when you apply a role.
How Kubernetes decides the verb
Each request to the API server is an HTTP request, and the authorizer turns its method into a verb before checking your roles:
| HTTP method | On one object | On a collection |
|---|---|---|
| GET, HEAD | get, or watch with ?watch=true | list, or watch with ?watch=true |
| POST | create | |
| PUT | update | |
| PATCH | patch | |
| DELETE | delete | deletecollection |
Requests to paths outside /api and /apis, such as /healthz or
/metrics, aren’t about resources at all. For these, the verb is simply the HTTP method in lower case, and
the rule names URLs instead of resources. Rules like this only work in a ClusterRole granted by a
ClusterRoleBinding:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: health-reader
rules:
- nonResourceURLs: ["/healthz", "/livez", "/readyz", "/metrics"]
verbs: ["get"]
Which verb each kubectl command needs
| Command | Verb | On |
|---|---|---|
kubectl get pod web-1 | get | pods |
kubectl get pods | list | pods |
kubectl describe pod web-1 | get, plus list on events | pods |
kubectl get pods --watch | list, then watch | pods |
kubectl create -f | create | the kinds in the file |
kubectl apply -f | get, then create or patch | the kinds in the file |
kubectl edit, label, annotate | patch | that object |
kubectl replace -f | update | the kinds in the file |
kubectl delete pod web-1 | delete | pods |
kubectl logs | get | pods/log |
kubectl exec, cp | create | pods/exec |
kubectl port-forward | create | pods/portforward |
kubectl scale | patch or update | deployments/scale (and other /scale) |
kubectl drain | create, plus patch on the node | pods/eviction |
kubectl create token | create | serviceaccounts/token |
kubectl get ... --as=jane | impersonate, plus the verb for the command | users |
When a command fails, the error names the verb and resource it was refused, for example
cannot list resource "pods" in API group "" in the namespace "payments". Copy those into your role.
The core API group, home of pods, Secrets and Services, is the empty string "".
get, list and watch aren’t harmless
The three read verbs look like the safe ones. Kubernetes’ own docs say
get, list and watch
can all return the full details of a resource. For most kinds that’s fine. For Secrets it means the values:
list on Secrets in a namespace reveals every password and token stored there, and
the RBAC good practices
page warns that list and watch effectively reveal Secret contents.
Give read-only roles a resource list instead of resources: ["*"], and leave Secrets out unless the job
needs them. If a workload needs one Secret, grant get on that one by name.
update vs patch, delete vs deletecollection
update and patch both change an object; they differ only in how the change is sent. A
role that grants one without the other breaks tools that use the other: kubectl apply, edit,
label and annotate send patches, kubectl replace sends a full update, and
controllers use either. Grant both unless you know every client.
deletecollection is a separate verb. It deletes every object of a kind that matches a selector in one
request, and delete doesn’t cover it. It can’t be limited to named objects, so think twice before
granting it on anything that matters.
Special verbs
These verbs don’t come from HTTP methods. The API server checks them for specific resources:
| Verb | Resource | What it allows |
|---|---|---|
bind |
roles, clusterroles (rbac.authorization.k8s.io) | Creating a binding to that role without holding its permissions yourself |
escalate |
roles, clusterroles (rbac.authorization.k8s.io) | Creating or changing a role to include permissions you don’t hold |
impersonate |
users, groups, serviceaccounts (core); uids, userextras/<name> (authentication.k8s.io) | Acting as that identity, with --as and --as-group |
approve |
signers (certificates.k8s.io) | Approving certificate signing requests for that signer, with update on certificatesigningrequests/approval |
sign |
signers (certificates.k8s.io) | Issuing the certificate for approved requests, with update on certificatesigningrequests/status |
attest |
signers (certificates.k8s.io) | Creating or updating ClusterTrustBundles linked to that signer |
use |
podsecuritypolicies (policy) | Nothing today: PodSecurityPolicy was removed in Kubernetes 1.25. Old roles may still list it |
bind and escalate exist because
the
RBAC API stops you handing out access you don’t have: you can only write a role, or bind one, if you hold every
permission in it. These two verbs switch that check off, and impersonate borrows someone else’s access
outright. Treat all three as admin rights, and limit them with resourceNames where you must grant them.
On signers, resourceNames take the signer’s name, such as example.com/my-signer, or a whole
domain as example.com/*. Recent versions also check a few verbs for narrow cases, such as
unsafe-delete-ignore-read-errors, required on top of delete to remove objects the API
server can’t read.
Subresources and their verbs
Some actions live on a subresource, written resource/subresource in a rule. A grant on
pods doesn’t include pods/exec or pods/log, and the verb is often not the one
you’d guess:
pods/logget: read container logs.pods/exec,pods/attach-
create: run a command or attach to a container. Before Kubernetes 1.35, exec over a websocket needed onlyget; from 1.35 theAuthorizePodWebsocketUpgradeCreatePermissionfeature, on by default, requirescreatefor websockets too. Remove both verbs from everyday roles. pods/portforwardcreate(alsogetover a websocket before 1.35): forward a local port to a pod.pods/evictioncreate: evict a pod, respecting its PodDisruptionBudget.pods/ephemeralcontainersupdate,patch: add a debug container to a running pod.deployments/scaleget,update,patch: read or change the replica count. Other workloads have their own /scale.serviceaccounts/tokencreate: mint a working token for that ServiceAccount.nodes/proxy-
Any verb reaches the kubelet API on each node, which can run commands in any container there.
Even
getis enough, through websocket requests. nodes/metrics,nodes/stats,nodes/pods,nodes/healthz,nodes/configz-
get: the narrower kubelet permissions monitoring agents should use instead. The last three come from fine-grained kubelet authorization, stable since Kubernetes 1.36.
Wildcards and resourceNames
verbs: ["*"] grants every verb on the listed resources, and
Kubernetes warns that a
wildcard also grants new resources, subresources and verbs as they’re added. A role that’s safe today can quietly
grow after an upgrade or an operator install. Spell verbs out in roles you write.
resourceNames limits a rule to named objects:
rules:
- apiGroups: [""]
resources: ["configmaps"]
resourceNames: ["app-config"]
verbs: ["get", "update", "patch"]
It has three limits that catch people out:
- It can’t limit
createon a resource, because the name may not be known when the request is checked. Subresources are fine: you can limitpods/execto named pods. - It can’t limit
deletecollection. -
It only limits
listandwatchwhen the client asks by name, with a field selector. Plainkubectl get configmapsis refused; this works:
kubectl get configmaps --field-selector=metadata.name=app-config
Find which verbs a resource supports
Not every resource supports every verb. TokenReviews and SubjectAccessReviews, for example, only support
create. Ask the cluster, which also covers your custom resources:
# Every resource and the verbs it supports
kubectl api-resources -o wide
# Only resources that support a verb, such as list
kubectl api-resources --verbs=list --namespaced -o name
# Everything you, or someone you may impersonate, can do in a namespace
kubectl auth can-i --list -n payments
kubectl auth can-i --list -n payments --as=system:serviceaccount:payments:api
The wide output adds a VERBS column; subresources aren’t listed, so use the table above for those.
kubectl auth can-i --list shows the verbs an identity holds, and using --as needs the
impersonate verb.
Example roles by job
A read-only role for a team’s own namespace, without Secrets:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: app-reader
namespace: payments
rules:
- apiGroups: [""]
resources: ["pods", "pods/log", "services", "configmaps", "events"]
verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
resources: ["deployments", "replicasets"]
verbs: ["get", "list", "watch"]
A deployer for a CI pipeline, which changes Deployments, Services and ConfigMaps but can’t exec into pods, read Secrets or create bare pods:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: app-deployer
namespace: payments
rules:
- apiGroups: ["apps"]
resources: ["deployments"]
verbs: ["get", "list", "watch", "create", "update", "patch"]
- apiGroups: ["apps"]
resources: ["deployments/scale"]
verbs: ["get", "update", "patch"]
- apiGroups: [""]
resources: ["services", "configmaps"]
verbs: ["get", "list", "watch", "create", "update", "patch"]
For a quick role on the command line, repeat --verb once per verb:
kubectl create role pod-reader -n payments \
--verb=get --verb=list --verb=watch --resource=pods
Grant these with a RoleBinding in each namespace the job needs, not a ClusterRoleBinding. Why that matters, and what the built-in view, edit and admin roles include, is on the explainer’s page.
Check what your roles allow
Paste your Roles, ClusterRoles and bindings, or the output of
kubectl get roles,rolebindings,clusterroles,clusterrolebindings -A -o yaml, into the free
Kubernetes RBAC Explainer. It lists who can do what in plain English,
resolves aggregated and built-in roles, and flags the verbs above that reach further than they look: reading
Secrets, exec, nodes/proxy, token creation, bind, escalate,
impersonate, wildcards and unknown verbs. It runs in your browser.
Designing roles for your own application rather than a cluster? The RBAC Matrix Builder lays them out as a grid and exports policy code.