Handbooks  /  The Kubernetes Handbook
Handbook~15 min readIntermediate
Deep Dive

Kubernetes,
and the desired state it chases.

Kubernetes looks like a pile of YAML and jargon, but there's one idea underneath everything: you declare the state you want, and a control loop relentlessly makes reality match it. Once that clicks, pods, deployments, services and self-healing all fall out of it.

01

The orchestration problem

Containers solved packaging: bundle an app with its dependencies so it runs the same everywhere. Great — for one container on one machine. But real systems run hundreds of containers across many machines, and that raises a swarm of hard questions: which machine does each container run on? What happens when one crashes, or a whole machine dies? How do containers find and talk to each other when they're constantly created and destroyed? How do you roll out a new version without downtime, or scale up under load?

Doing all that by hand doesn't work. Kubernetes is a container orchestrator: it automates placement, healing, networking, rollouts, and scaling across a cluster of machines. It turns "a fleet of containers on a fleet of servers" from a manual nightmare into something you declare and it manages.

02

Pods — the smallest unit

You might expect Kubernetes to schedule containers directly. Instead the smallest unit is a pod: one (or a few tightly-coupled) containers that share a network address and storage and are always placed together on the same node. Most pods hold a single app container; a second "sidecar" container (a log shipper, a proxy) is added when it must live right next to the main one.

The crucial property: pods are ephemeral. They can be created, killed, and rescheduled at any moment — a pod has no stable identity or IP you should rely on. So you don't create pods by hand and babysit them; you declare a higher-level object that owns pods and replaces them as needed. That's the next piece.

03

Deployments & ReplicaSets

A Deployment is how you actually run an app. You declare: "run N replicas of this container image, with these resources." Under the hood a ReplicaSet ensures exactly N identical pods exist — if one dies, it makes another; if you change N, it adds or removes pods. You never touch individual pods; you edit the Deployment's desired count and image.

Deployments also give you rolling updates: change the image and Kubernetes gradually replaces old pods with new ones, keeping the app available throughout, and can roll back if the new version misbehaves. This is the everyday interface: declare what you want running, and let the Deployment keep it that way.

→ The layering

You manage a Deployment → it manages a ReplicaSet → which manages Pods → which run containers. Each layer exists so failures and changes are handled automatically at the level below.

04

Services & networking

Pods are ephemeral with changing IPs, so how does anything reliably reach them? A Service gives a stable virtual address and DNS name that fronts a dynamic set of pods (selected by label). Traffic to the Service is load-balanced across the healthy pods behind it, and as pods come and go the Service tracks them automatically. Your other services just call payments and never worry about which pods exist right now.

This is service discovery and load balancing built in: the Service is the stable front door over an ever-changing fleet. Types range from internal-only (ClusterIP) to externally exposed (LoadBalancer), and an Ingress adds HTTP routing on top. The pattern mirrors classic load balancing and service discovery — Kubernetes just makes it declarative.

05

The core idea: desired state & the control loop

Everything above is a special case of one mechanism. This is the whole of Kubernetes.

Kubernetes is declarative: you don't issue commands ("start a pod on node 3"), you declare desired state ("I want 4 replicas of this running") and store it in the cluster. Then controllers run a continuous reconciliation loop: observe the actual state, compare it to the desired state, and take action to close any gap — forever.

The reconciliation loop — running constantly
Observe
What's actually running?
Compare
vs. desired state
Act
create/delete to converge
Declared 4 replicas but 3 are running? The gap is 1 — the controller creates a pod. This never stops.

This is why Kubernetes self-heals: a pod crashes, actual drops below desired, the controller notices the mismatch and creates a replacement — no human, no alert-driven fix, just the loop converging. Scaling, rollouts, and recovery are all the same loop chasing whatever state you declared.

06

The scheduler

When a new pod needs to run, the scheduler decides which node it lands on. It filters nodes that can't fit the pod (not enough CPU/memory, missing constraints) and scores the rest to pick a good home, balancing the cluster. You can influence it with resource requests/limits (how much CPU/memory a pod needs), node affinity (prefer/require certain nodes), and taints/tolerations (keep pods off, or allow onto, special nodes).

Getting resource requests right matters: request too little and pods get packed and starved; too much and you waste the cluster. The scheduler is the piece that turns "run this pod" into "run it here," and it's how Kubernetes uses a fleet of machines efficiently.

07

Config, health & autoscaling

A few more pieces complete the picture. ConfigMaps and Secrets inject configuration and credentials into pods so images stay generic and environment-specific values live outside them. Health probes let Kubernetes know a container's real state: a liveness probe detects a hung container and restarts it; a readiness probe detects one that isn't ready to serve yet and holds traffic back until it is (crucial during startup and rollouts).

And autoscaling closes the loop on load: the Horizontal Pod Autoscaler (HPA) watches metrics like CPU and adds or removes replicas to match demand, while cluster autoscaling can add or remove nodes. Combined with self-healing, you get a system that repairs and resizes itself — the payoff for describing everything as desired state.

Liveness probe

  • "Is it alive?"
  • Fails → restart the container
  • Catches hangs/deadlocks

Readiness probe

  • "Is it ready to serve?"
  • Fails → remove from Service (no traffic)
  • Protects during startup & rollouts
08

Do you need Kubernetes?

Kubernetes is powerful, and it's complex — a real operational surface with its own failure modes, upgrades, and learning curve. It earns that cost when you run many services across many machines and genuinely need automated scaling, self-healing, rolling deployments, and service discovery working together. At that scale, doing it yourself is worse.

But for a single app or a handful of services, Kubernetes is often over-engineering. A managed platform (PaaS), serverless functions, or simple container hosting will ship you faster with far less to operate, and you can adopt Kubernetes later if scale demands it. The honest question isn't "is Kubernetes good?" (it is) but "does my system have the scale and complexity that justify its complexity?"

Reach for itMany services, many nodes — needing autoscaling, self-healing, rollouts, discovery together.
Skip itOne app / a few services — a PaaS, serverless, or simple hosting ships faster with less to run.
Frequently asked

Quick answers

What is Kubernetes?

A container orchestrator: you declare desired state (replicas, image, resources) and it continuously makes reality match — scheduling containers, restarting failures, load-balancing, and autoscaling across a cluster.

What is a pod?

The smallest deployable unit: one or more tightly-coupled containers sharing a network and storage, scheduled together. Pods are ephemeral, so you manage higher-level objects (Deployments) that create and replace them.

What is the control loop?

Controllers continuously compare desired vs actual state and act to close the gap. It's why Kubernetes self-heals: if a pod dies, the mismatch triggers a replacement automatically.

When do you need it?

When you run many services across many machines needing automated scaling, healing, rollouts, and discovery. For one app or a few services, a PaaS/serverless/simple hosting is usually simpler and enough.

The Kubernetes Handbook · declarative desired state, from pods to self-healing · Vibe Engines Handbooks · 2026
Finished this one? 0 / 29 Handbooks done

Explore the topic

See this alongside everything else on the same subject — handbooks, system designs, challenges and tools, in one place.