Mapping HTTP Methods to API Verbs

Understanding the mapping between standard HTTP methods and Kubernetes API verbs is essential. While Kubernetes uses RESTful HTTP methods on the wire, it uses distinct API verbs for Access Control (RBAC) and auditing.

Why this matters

This distinction allows for finer-grained control, particularly distinguishing between viewing a static list of objects versus streaming changes to them.

1. Resource Request Mapping

For standard API resources (like Pods, Deployments, and Services), Kubernetes maps HTTP methods to API verbs as follows:

HTTP Method	Kubernetes API Verb	Context & Behavior
POST	create	Used to create a new resource.
GET, HEAD	get	Retrieving an individual resource (e.g., /api/v1/namespaces/default/pods/my-pod).
GET, HEAD	list	Retrieving a collection of resources (e.g., /api/v1/namespaces/default/pods).
GET	watch	Watching a resource or collection for changes. This maps to watch specifically when the HTTP GET request includes the ?watch query parameter.
PUT	update	Replacing an existing resource entirely.
PATCH	patch	Partially modifying an existing resource.
DELETE	delete	Removing an individual resource.
DELETE	deletecollection	Removing a collection of resources (e.g., kubectl delete pods --all).

2. Engineering Insight

List vs. Watch Unlike standard REST where a GET is just a GET, Kubernetes differentiates list (getting the state now) from watch (getting a stream of future updates). This distinction allows administrators to grant permission to view the current state of the cluster without granting the performance-intensive privilege of establishing persistent watches.

Create vs. Update While PUT is technically capable of creating a resource if the name is known, Kubernetes generally relies on POST for creation and PUT for updates. Internally, the API server classifies PUT requests as either create or update based on the state of the existing object, but for RBAC authorization purposes, PUT maps to the update verb.

3. Non-Resource Request Mapping

Requests to system endpoints that do not correspond to Kubernetes objects (such as /healthz, /metrics, or /api) are classified as Non-Resource Requests.

For these requests, the API verb is simply the lower-cased HTTP method:

HTTP Method	API Verb	Example Endpoint
GET	get	/healthz, /version, /metrics
POST	post	/api (Discovery)

4. Specialized API Verbs

There are several abstract verbs used in Kubernetes RBAC that do not map directly to a single HTTP method but represent specific high-privilege actions:

• impersonate: Used when a client requests to act as another user or group using impersonation headers.
• bind and escalate: Used for roles and clusterroles in the RBAC API group to control privilege escalation.
• approve and sign: Used for CertificateSigningRequests (CSRs).
• proxy: Used to control access to the proxy subresource (tunneling connections).