API machinery
API Machinery and Server-Side Apply
1.Resources, kinds and URLs
- Resource vs kind : the URL uses the resource (
deployments), the body the kind (Deployment). - Core group :
/api/v1, apiVersionv1. Named :/, apiVersionapis/ GROUP/ VERSION apps/v1. - Identity = group + resource + namespace + name. v1beta1 and v1 are two views of one stored object, so names clash.
Discovery
/api and /apis list what is served. Aggregated discovery (stable since 1.30) returns every group in 2 requests. Schemas at /openapi/v3.2.A request, step by step
- Every request : authentication (401), audit and impersonation, APF (429), authorization (403, RBAC and Service Accounts).
- Writes : mutating admission, object schema validation (422), validating admission (Admission Control), then etcd. Stale resourceVersion : 409.
- Unknown fields are dropped with a Warning.
fieldValidation=Strictmakes them a 400. - Reads skip admission and come from the watch cache. While it is cold, watches and unpaginated or filtered lists get 429 with
Retry-After.
3.resourceVersion and conflicts
- resourceVersion (RV) : a string, new on every write. Pass it back unmodified. Compare as integers only within one group + resource (required since 1.35).
- PUT sends
metadata.. Stale ? 409 Conflict. GET again, reapply your change, retry.resourceVersion - Patches skip this check unless they carry the RV or a JSON Patch
testop.
| Field | Changes on |
|---|---|
| resourceVersion | Every write, status and labels too |
| generation | Desired state (spec) changes |
| observedGeneration | Set in status by the controller. Equal to generation : status is current |
How controllers use observedGeneration : Controllers and Reconciliation.
In short : Every request passes authentication, APF and authorization, and writes also pass admission and validation. resourceVersion changes on every write, so a stale PUT gets 409, while generation moves only when the desired state does.
1.List, then watch
- A LIST returns the items and the collection's RV. WATCH from there, not from an item's RV.
- etcd keeps about 5 min of history. Older RV : 410 Gone. Clear the cache, re-list.
- Bookmarks carry only a fresh RV for reconnects. No interval promise.
- Pages :
limit=Nreturnsmetadata.continue. All pages share one RV. Tokens expire in about 5 min. - Streaming list (WatchList, beta, on) : one WATCH with
sendInitialEvents=truesends the state as ADDED events, then a BOOKMARK.
2.Ways to write an object
| Method | HTTP / Content-Type | Conflicts | Use for |
|---|---|---|---|
| update | PUT, the whole object | 409 if metadata.resourceVersion is stale | Read-modify-write, you write the retry loop |
| JSON Patch | PATCH application/json-patch+json | Only via a test op or the RV | Exact path ops, compare-and-set |
| JSON Merge Patch | PATCH application/merge-patch+json | None, last write wins | Small partial edits |
| Strategic Merge Patch | PATCH application/strategic-merge-patch+json | None | Built-ins only, never CRDs. Superseded by SSA |
| Server-Side Apply | PATCH application/apply-patch+yaml ?fieldManager= | 409 on another manager's field unless force=true | Declarative config, controllers, create-or-update |
3.Server-Side Apply (SSA)
- Stable since 1.22. The body is your partial intent : it creates the object if missing, patches it otherwise.
managedFieldslists each manager, its operation (Apply or Update) and the fields it owns.- Apply over another manager's field : 409 unless
force=true. Update never conflicts, it takes ownership. Same value : shared. - A field you drop is removed only if no one else owns it. Controllers should always force.
- Lists merge by
x-kubernetes-list-type(atomic, set, map). CRD lists are atomic unless marked (Custom Resources (CRDs)).
Gotchas
- A renamed manager stays on as a second owner.
- Drop replicas before the HPA owns it : it resets to 1.
- Clear managedFields with
[{}], not[].
In short : Watch from the list's RV and re-list on 410. A PUT checks resourceVersion, most patches do not, and SSA tracks an owner per field instead : apply over another manager's field and you get 409.
1.API Priority and Fairness
- Stable since 1.29. Each apiserver has 600 seats : 400 inflight + 200 mutating.
- Priority levels split them by
nominalConcurrencyShares, and lend and borrow. - FlowSchemas match by ascending
matchingPrecedence. First match wins. - A flow = FlowSchema + distinguisher (ByUser, ByNamespace). Shuffle sharding picks its queue.
- A LIST costs seats by object count. exec and logs bypass APF.
Gotchas
- Edits to suggested objects revert each minute unless annotated
apf..kubernetes. io/ autoupdate-spec: "false" - Replicas under one ServiceAccount are one flow.
2.Deprecation and version skew
| API level or component | Rule |
|---|---|
| Alpha API | Off by default. Can be removed in any release without notice |
| Beta API | New betas off by default since 1.24. Still served 9 months or 3 releases after deprecation, whichever is longer |
| GA API | Can be deprecated, never removed within v1 |
| kube-apiserver (HA) | Instances within 1 minor of each other |
| controller-manager, scheduler | Not newer than kube-apiserver, up to 1 older |
| kubelet, kube-proxy | Not newer than kube-apiserver, up to 3 older |
| kubectl | Within 1 minor of kube-apiserver, either way |
3.Commands
| Command | Shows |
|---|---|
kubectl api-resources -o wide | Discovery as a table : APIVERSION, NAMESPACED, KIND, VERBS |
kubectl get pods -w --output-watch-events | List, then watch, printing each event type |
kubectl apply --server-side --field-manager=ci-cd -f deploy.yaml | SSA as manager ci-cd (default kubectl). A conflict fails with 409 |
kubectl apply --server-side --force-conflicts -f deploy.yaml | Take the conflicting fields, become sole owner |
kubectl get deploy web -o yaml --show-managed-fields | managedFields : who owns which field, Apply or Update |
kubectl get flowschemas,prioritylevelconfigurations | APF config |
In short : APF queues each flow fairly, so one noisy client cannot starve the rest. Alpha APIs can vanish any time, a deprecated beta is served for at least 3 releases, GA stays for all of v1, and the kubelet may trail kube-apiserver by 3 minors but never lead it.