Types of API Requests in Kubernetes

It is crucial to distinguish between the HTTP verbs used on the wire (REST) and the API verbs used for access control (RBAC), as they map to each other but are distinct concepts.

1. HTTP Methods vs. Kubernetes API Verbs

The Kubernetes API is RESTful. When you send an HTTP request, Kubernetes maps that method to a specific internal "verb" for Authorization (RBAC) purposes.

HTTP Method	Kubernetes API Verb	Description
POST	create	Creates a new resource.
GET, HEAD	get	Retrieves an individual resource (e.g., specific Pod).
GET, HEAD	list	Retrieves a collection of resources (e.g., all Pods).
GET	watch	Streams changes to an object or collection over time.
PUT	update	Replaces an existing resource entirely.
PATCH	patch	Partially modifies an existing resource.
DELETE	delete	Removes an individual resource.
DELETE	deletecollection	Removes a collection of resources.

2. The Nuance of Update (PUT) vs. Patch (PATCH)

Understanding the difference between these two write operations is critical for writing robust controllers and automation.

Update (PUT)

• Behavior: This is a full replacement of the object. You must provide the complete resource definition.
• Concurrency Control: It requires optimistic locking. You must provide the resourceVersion of the object you are updating. If the version on the server has changed since you read it, the request fails with a 409 Conflict.

Patch (PATCH)

• Behavior: This allows you to modify specific fields without sending the entire object. It is generally safer for automation as it avoids overwriting fields managed by other controllers.
• Patch Types: Kubernetes supports four distinct Content-Types for patching:
  1. JSON Patch (application/json-patch+json): Executes a sequence of operations (add, remove, replace) defined in RFC 6902.
  2. JSON Merge Patch (application/merge-patch+json): A simple merge where fields present in the request replace those in the target (RFC 7386).
  3. Strategic Merge Patch (application/strategic-merge-patch+json): A Kubernetes-specific extension that knows how to merge lists based on specific "patch keys" (e.g., merging containers by name rather than replacing the whole list).
  4. Server-Side Apply (application/apply-patch+yaml): The modern standard where the server tracks field ownership to resolve conflicts automatically.

3. Specialized API Verbs

Beyond the standard CRUD operations, Kubernetes defines specialized verbs for specific security and operational actions. These are primarily used in RBAC roles to grant fine-grained permissions.

• impersonate: Allows a user to act as another user or group.
• proxy: Allows access to the proxy subresource.
• bind and escalate: Used within RBAC resources to control privilege escalation.
• approve and sign: Used for CertificateSigningRequests.

4. Non-Resource Requests

Not all requests target specific Kubernetes objects (like Pods). Requests to system endpoints are classified as Non-Resource Requests.

• Examples: /healthz, /version, /metrics, /api.
• Verbs: These endpoints use the lowercase HTTP method directly as the verb (e.g., get, post) for authorization checks.