The Kubernetes API and the Declarative Model

Why this matters

A newcomer shells into a cluster and deletes a misbehaving pod by hand. Seconds later an identical pod appears with a new name and the newcomer concludes the cluster is haunted. Nothing is haunted: a ReplicaSet controller observed one fewer replica than desired and created a replacement. Every surprise in Kubernetes traces back to this model. Someone, human or controller, declares state; controllers reconcile it. If you cannot name the controller that owns an object, you cannot predict what the cluster will do next, and every kubectl command is a guess.

Concepts

The API server is the single front door: all reads and writes go through it, and etcd behind it stores the declared state. A Kubernetes object carries metadata (name, namespace, labels), a spec (the desired state you wrote) and a status (the observed state controllers report back). Labels are the wiring: Services select pods by label, Deployments manage ReplicaSets by label, and a wrong label quietly disconnects the chain.

Controllers run compare-and-repair loops. The Deployment controller keeps the ReplicaSet count right, the ReplicaSet controller keeps the pod count right, the endpoints controller keeps the Service target list right. None of them runs once and exits; each watches, compares actual against desired, and acts. A note on hand edits: kubectl edit updates the live object in the API server, and that change stays until something else rewrites the field. Kubernetes alone does not re-read a manifest file from your laptop and revert the edit on the next pass. An edit is lost when a field is owned by a controller or a GitOps tool that reapplies its own desired state (for example a Deployment recreating pods from its template, or a GitOps agent re-applying the repo). So the rule is manifest-first: the repo holds the intent, the cluster is a projection of those files, and hand edits are for diagnosis, not for lasting change.

Imperative commands (run, expose, scale with flags) write the same objects but leave no record of intent in the repo. Lesson M16 shows why that debt compounds; the habit to build here is manifest-first: if an object matters, it exists as a file, reviewed and versioned, and the cluster is a projection of those files.

Worked example

A demo namespace runs a three-replica web Deployment. The learner applies a manifest that changes the container image tag, then watches: the Deployment creates a new ReplicaSet with the new template, scales it up one pod at a time while scaling the old one down, and the Service keeps sending traffic to ready pods throughout. Then the learner edits a live pod label by hand and watches the Service drop that pod from its endpoint list within seconds, restoring it on the next apply. Two commands, one model: desired state in, reconciliation out.

Common wrong move

Treating pods as pets: hand-creating pods, hand-editing live objects, and debugging by restarting things until the symptom moves. Pods are the cheapest, most disposable unit in the system; anything you cannot delete and recreate from a file is unmanaged by definition. The L25 lab makes this concrete by tracing a CrashLoopBackOff to its config cause through the owning chain instead of by restarting the pod.