Objects and the Kubernetes API

The API is not one flat namespace of kinds. It is split into groups, each independently versioned:

Within a group, a version carries a maturity level baked into its name: v1alpha1 (disabled by default, may change or vanish without notice), v1beta1 (enabled by default, well-tested, but the schema may still change in incompatible ways before graduating), and v1 (GA — generally available, supported for as long as the group exists). A resource can be served simultaneously under several versions (the API server converts between them), and kubectl get <resource>.<version>.<group> pins a specific one, e.g. kubectl get deployments.v1.apps. Derived from Kubernetes Docs — The Kubernetes API and Kubernetes Docs — API concepts.

Kubernetes' API deprecation policy gives every API a documented lifetime before it can be removed:

The deprecated API migration guide is the authoritative table of every API that has actually been removed, the release it was removed in, and its replacement — the reference to check before upgrading a cluster, not the general policy above. The best-known historical case, extensions/v1beta1 and apps/v1beta1/apps/v1beta2 Deployments, was removed in 1.16; any manifest still written against them (as in the 2017 sampler’s listings) must be rewritten against apps/v1 before it will apply to a 1.37 cluster.

A client never has to guess which groups, versions and kinds a given cluster serves — it discovers them from the API server itself:

kubectl api-resources is how you find that deploy is a short name for deployments, whether a kind is namespaced, and which apiVersion to write in a manifest, and it is exactly what kubectl explain and shell completion query under the hood. Derived from Kubernetes Docs — API concepts: API discovery.

kubectl proxy opens a local HTTP proxy to the API server that reuses the current kubeconfig’s credentials, which makes it the simplest way to talk to the API directly without handling a bearer token:

This is the same mechanism every controller uses instead of polling: it lists the current objects once, then keeps a long-lived watch connection open and reacts to ADDED / MODIFIED / DELETED events as they arrive — the "observe" step of the reconciliation loop from Introduction and Architecture. Source: Kubernetes Docs — Use an HTTP proxy to access the API.

Every object carries metadata.resourceVersion, an opaque string set by etcd and bumped on every write. It has two jobs: telling a watch where to resume (?resourceVersion=…​), and enforcing optimistic concurrency on updates. When a client sends a PUT, it includes the resourceVersion it last read; if the object has changed since (its stored resourceVersion no longer matches), the API server rejects the write with 409 Conflict instead of silently overwriting someone else’s change. kubectl apply and controllers handle this by re-reading and retrying; hand-written clients must do the same rather than retry blindly with a stale copy. Derived from Kubernetes Docs — API concepts: resource versions.

Book 1’s own numbers (a 64-character value limit with no separate prefix rule) predate the object schema being formalised this precisely; the limits above are what a 1.37 API server actually validates.

A selector is how a Service, ReplicaSet, NetworkPolicy or kubectl query picks a set of objects by their labels. Two forms exist, and a selector can freely mix them (comma-separated terms are ANDed together):

Relabelling a running Pod so it no longer matches its ReplicaSet’s selector — the last command above removes the selector label from one Pod (app.kubernetes.io/name-) and marks it debug=true so it is still easy to find — is exactly the Book 1 ch. 3 technique for isolating one misbehaving replica: the ReplicaSet controller immediately creates a fresh replacement Pod, while the relabelled one keeps running for inspection outside the controller’s reach. Source: Kubernetes Docs — Labels and Selectors.

Kubernetes documents a shared set of labels so that dashboards, kubectl, and third-party tooling can all reason about "which application does this object belong to" the same way, across every workload in a cluster. Every Bookshelf manifest in this section applies them consistently:

Only app.kubernetes.io/name (or another stable subset) should ever appear in a Deployment’s or Service’s own spec.selector — instance and version change across rollouts and environments, and a workload controller’s selector (Deployment, ReplicaSet, StatefulSet, DaemonSet) is immutable once created, so putting a changing label in it would require recreating the object. A Service’s spec.selector can be changed in place, which is exactly what blue/green switching in Deployment Strategies relies on. Source: Kubernetes Docs — Recommended labels.

A finalizer is a string in metadata.finalizers that a controller adds to an object it needs to run cleanup logic for before that object is actually removed. kubectl delete (or any DELETE call) on an object with finalizers only sets metadata.deletionTimestamp — the object stays visible, stuck "Terminating", until every controller that owns one of its finalizers has finished its cleanup and removed its own entry. The built-in kubernetes.io/pv-protection and kubernetes.io/pvc-protection finalizers (which stop a bound PersistentVolume/ PersistentVolumeClaim from being deleted, covered in Persistent Volumes and Storage Classes) and the foregroundDeletion finalizer above are the two most commonly seen in practice; a Pod stuck Terminating after a node has already disappeared is almost always a finalizer (or a kubectl delete --grace-period=0 --force, which skips graceful shutdown but still waits on finalizers) situation, not a hung kubectl. Source: Kubernetes Docs — Finalizers.