Chapter 12: The Ecosystem
Topic 76

When You Outgrow a Single Host → Kubernetes

BoundaryKubernetes

This is the boundary the whole book has held to, now crossed and named. Docker builds and runs containers on one host; Kubernetes orchestrates them across many. Everything in this course — the image, the layers, the network, the volumes, the hardening — was the work of making one container right on one machine.

When you need that container running reliably across a fleet, the job changes shape, and Kubernetes is where this course hands off to its sibling. This topic draws the line precisely and points across it. It does not teach Kubernetes — that is the Kubernetes Deep Dive course, which assumes exactly the good image this book taught you to build.

The Contract Sentence

Docker is build-and-run on a single host; Kubernetes is orchestration across many. The dividing line is not "small versus large" — it is "one machine's daemon versus a scheduler placing work over a cluster." Recognizing which problem you actually have is the first decision, and it is more often answered wrong by adopting too much than too little. If one host holds your workload, you do not have an orchestration problem yet.

Where the boundary falls
One host — Docker
Builds and runs containers on a single machine. Everything this book taught: the image, layers, network, volumes, and hardening on one host.
Many hosts — Kubernetes
Schedules and self-heals the same OCI images across a fleet — multi-node placement, fleet-scale rolling deploys, and a continuously reconciled desired state.

What One Host Can't Give You

A single Docker host can restart a crashed container, but four things sit beyond its reach. It cannot reschedule work when the whole node dies — a restart policy is useless if the machine running it is gone. It cannot schedule across many machines by capacity. It cannot roll out a new version across a fleet without downtime. And it cannot hold a declared desired state that the cluster continuously reconciles toward. Those are orchestration problems, and they begin precisely where one host ends.

Kubernetes Runs the Same Images You Built

Kubernetes does not ask you to rebuild anything. It pulls the exact OCI driftwood/web image you built, scanned, signed, and pushed, and runs it via containerd — the runtime from topic 73. The build work in this book is the input to the orchestration work in the next, unchanged. If you find yourself rebuilding an image to "make it Kubernetes-ready," you have misread the boundary: a good OCI image already is ready.

Compose and Swarm as the Stepping Stones

The path through this book has been a gradient. Compose declared multi-container intent on one host; Swarm stretched that same declarative idea across a few nodes; Kubernetes generalizes it to a fleet with self-healing, autoscaling, and a full ecosystem. The mental model — declare the desired state, let the system reconcile toward it — is identical at each step. Only the scope grows, from one machine to several to many.

The Hand-Off

When self-healing across nodes, multi-node scheduling, fleet-scale rolling deploys, or declarative desired-state become requirements rather than nice-to-haves, the right next move is the Kubernetes Deep Dive course. It starts exactly where this boundary ends, and it assumes the hardened, slim, signed image this book taught you to build. The build-and-run job is finished here; the orchestrate-across-many job begins there.

Stay on a single host until a concrete need forces the move, and carry the exact image forward when it does. The discipline this course drilled — multi-stage builds, non-root users, scanning, signing, digest pinning — is not wasted at the boundary; Kubernetes magnifies a good image and magnifies a bad one equally. The next topic walks that whole single-host pipeline end to end before the hand-off.

Compose / Swarm vs Kubernetes

Compose — declares multiple containers on one host for development and small deployments. Choose it for local stacks and single-machine apps. Swarm — extends that to a small cluster with minimal new concepts. Choose it for a few nodes when simplicity wins.

Kubernetes — orchestrates containers across a fleet with self-healing, autoscaling, rolling deploys, and a deep ecosystem. Choose it when you have genuinely outgrown one host and need the cluster to hold desired state on its own. All three run the same driftwood/web OCI image.

Common Mistakes
  • Adopting Kubernetes for a workload that comfortably fits one host — you take on a cluster's worth of operational complexity to solve a problem a single Docker host or Compose already handles.
  • Believing the move to Kubernetes requires re-engineering your images — it consumes the same OCI artifact unchanged; if you are rebuilding to "make it Kubernetes-ready," you have misread the boundary.
  • Treating Docker's single-host restart policy as equivalent to Kubernetes self-healing — a restart: always policy cannot save you when the node itself dies, which is precisely the gap orchestration fills.
  • Skipping the image discipline of this book and expecting Kubernetes to compensate — a fat, root-running, unscanned image is just as bad across a fleet, only multiplied; orchestration does not fix a poor artifact.
Best Practices
  • Stay on a single host with Compose until a concrete need — node-failure resilience, multi-node scale, fleet rollouts — forces the move, so complexity is added deliberately, not by default.
  • Carry the exact OCI image forward into Kubernetes without rebuilding, since the build work in this book is the unchanged input to orchestration.
  • Invest in the image and hardening this book taught first, because Kubernetes magnifies a good image and magnifies a bad one equally.
  • Move to the Kubernetes Deep Dive when desired-state-across-many-nodes is the requirement — the sibling course starts exactly where this boundary ends.
Comparable tools Kubernetes · GKE · EKS · AKS the fleet orchestrator and its managed forms Docker Swarm · HashiCorp Nomad lighter-weight orchestration alternatives Docker Compose the single-host sibling — all schedule the same OCI image

Knowledge Check

What is the contract sentence dividing Docker from Kubernetes?

  • Docker builds and runs containers on one host; Kubernetes orchestrates them across many
  • Docker is the right tool for small apps while Kubernetes is strictly reserved for large, high-traffic ones
  • Docker uses OCI images while Kubernetes requires its own cluster-native image format
  • Docker runs ordinary containers while Kubernetes runs lightweight virtual machines instead

Which problem does a single Docker host fundamentally fail to solve?

  • Rescheduling work onto another machine when the whole node it runs on dies
  • Restarting a single container that crashed while staying on that same host
  • Applying memory and CPU cgroup limits to a container it is already running
  • Pulling and running the exact OCI image you built, signed, and pushed

What does Kubernetes require of the image you built in this course?

  • Nothing new — it pulls and runs the exact OCI image unchanged via containerd
  • A rebuild into a Kubernetes-specific image format before the cluster can run it
  • Stripping out the non-root hardening so the cluster scheduler can manage the container
  • A running Docker daemon installed on every node to interpret and run the image

When is adopting Kubernetes premature?

  • When the workload comfortably fits one host that Compose or a single Docker host already handles
  • When you need work rescheduled automatically onto a surviving node after a whole machine fails or is drained
  • When you need fleet-scale rolling deploys across many nodes with no downtime
  • When you need the cluster to hold and continuously reconcile a declared desired state

You got correct