Swarm gave you a cluster with just enough ideas and a gentle learning curve. Kubernetes gives you the industry standard in exchange for a new vocabulary. The good news is that you already have the concepts: desired state, reconciliation, replicas, networking between nodes and secrets mounted as files. This lesson puts new names on familiar ideas and adds the ones that are missing, without deploying the whole of Aurora Libros just yet.

1. Why Kubernetes exists and what it adds
2. The declarative model and controllers
3. Cluster architecture
4. The runtime after dockershim: CRI and OCI
5. The fundamental objects at a glance
6. Pod: the unit of deployment
7. ReplicaSet and Deployment
8. Service, its types and Ingress
9. ConfigMap and Secret
10. Namespace
11. PersistentVolume, PersistentVolumeClaim and StorageClass
12. Job, CronJob, StatefulSet and DaemonSet
13. Anatomy of a manifest: labels and selectors
14. Essential kubectl, translated from Docker
15. A local cluster to practice on
16. Docker → Kubernetes glossary

Kubernetes was born at Google out of the experience with Borg and was donated to the CNCF in 2015. Its goal was not to improve on Swarm but to solve orchestration at the scale of thousands of nodes and teams, which is why its design is more ambitious and also more complex.

The last row is what decides it in most organizations. The first is what changes your way of thinking the most, and it is the one we will look at in depth.

The conceptual core is identical to Swarm's: you describe the desired state and the system maintains it. The difference is that Kubernetes generalizes it: everything is an object in a database (etcd), and for every type of object there is a controller running the same loop.

That pattern is called the reconciliation loop, and it explains behaviors that are baffling at first:

• You delete a Pod created by a Deployment and it comes back: its controller sees that replicas are missing.
• You edit a Pod by hand and your change disappears at the next deployment: the source of truth is the Deployment's template.
• You apply a manifest twice and nothing happens: you are not describing actions, you are describing destinations. The operation is idempotent.

Notice the property that makes the design robust: nobody talks to anybody except the kube-apiserver. The scheduler does not call the kubelet; it writes into the API that a Pod belongs on a certain node, and the kubelet on that node, which is watching the API, acts. Everything goes through the same point of authentication and auditing.

In 2022, Kubernetes 1.24 removed dockershim, the adapter that let it use Docker Engine as a runtime. That produced "Kubernetes drops Docker" headlines that confused everybody.

What actually happened is far less dramatic:

• Kubernetes talks to runtimes through an interface called CRI (Container Runtime Interface).
• Docker Engine does not implement CRI, so an adapter (dockershim) maintained by the project itself was needed.
• That adapter was retired, and nodes use containerd or CRI-O directly, both of which do speak CRI. And containerd is, precisely, the same component Docker Engine has been using internally since 01-03.

Your images are still exactly as valid as before. What you build with docker build is an OCI image, a standard format, not a "Docker" format. The ghcr.io/auroralibros/aurora-api:2.0.0 your pipeline produced runs on containerd with no modification whatsoever. The only thing that changed is which program starts it on the node.

A Pod is a group of containers that share a network namespace (same IP, they talk over localhost), an IPC namespace and, optionally, volumes. It is the unit the scheduler places and the unit that scales: in Kubernetes you do not replicate containers, you replicate Pods.

You almost never create a Pod by hand, for one compelling reason: a Pod does not recover. If the node dies, the Pod dies with it and nobody recreates it; it is the exact equivalent of a docker run without --restart. What you create is a Deployment, which through its ReplicaSet guarantees there are always as many Pods as you asked for.

Most Pods have a single container. The multi-container case is the sidecar pattern: a helper container accompanying the main one —a log collector, a service mesh proxy, a file synchronizer— that benefits from sharing the network and volumes.

The chain of responsibility has three links, and understanding it avoids a lot of confusion:

The ReplicaSet only knows how to count: it keeps N Pods matching its selector. The Deployment manages ReplicaSets: when the image changes it creates a new one, fills it while draining the old one, and keeps the old one at zero replicas so the change can be undone. That empty ReplicaSet you see in kubectl get rs is not garbage: it is your rollback history (06-07).

A warning: a Deployment's selector is immutable. If you change it, the object has to be deleted and recreated. It is worth choosing the labels well the first time.

Pods are cattle, not pets: they are born and die with different IPs. A Service provides a stable virtual IP and DNS name in front of a changing set of Pods, selected —again— by labels.

Pods reach it over DNS as aurora-cache inside the namespace, or aurora-cache.aurora.svc.cluster.local from outside it: the equivalent of the DNS-by-service-name you had in Compose and Swarm.

One LoadBalancer per service gets expensive fast: each one is a billed load balancer at the provider. The standard answer is an Ingress: a single entry point that routes by host and path towards several Services.

A detail that throws people the first time: the Ingress object does nothing on its own. It is a statement of intent that needs an ingress controller installed in the cluster (ingress-nginx, Traefik, HAProxy...) to read it and configure the real proxy. Without a controller, the object exists, raises no error and the traffic goes nowhere.

Both are consumed the same way, and there are two forms with different implications:

Important warning about Secret. A Kubernetes Secret is in base64, which is not encryption: anybody with read permission on the object sees the value with a base64 -d. On top of that, etcd does not encrypt at rest unless that is explicitly enabled. For production you have to enable encryption at rest, restrict access with RBAC and consider an external manager (Vault, Sealed Secrets, your cloud provider's secret manager via the CSI driver). This is a decision you must agree with the security officer in your organization, not an acceptable default.

And one practical difference from Swarm: mounted as a volume, an updated Secret or ConfigMap propagates to the Pod's file without restarting it (with a delay of up to a minute); injected as an environment variable, it never updates until the Pod is recreated.

A Namespace is a logical partition of the cluster. It gives you three things: names that do not collide (there can be an aurora-api in aurora and another in aurora-staging), a scope for RBAC and quotas, and a network boundary if you use NetworkPolicy. It is not a strong security boundary in itself: it isolates the API, not the kernel.

With kubectl config set-context --current --namespace=aurora you save yourself typing -n aurora on every command.

Kubernetes separates who asks for storage from who provides it, which is exactly what Swarm was missing.

Almost every cloud provider's block disk is RWO, and from that comes a very real limit: a PVC of that kind cannot be mounted simultaneously in Pods on different nodes. It is the technical reason aurora-db does not scale by replicating Pods, and we will deal with it in 06-06.

The DaemonSet is literally Swarm's mode: global. The StatefulSet is what Swarm did not have: each replica gets a stable name and its own volume, survives a restart with the same identity and starts and stops in order. It is what anything stateful needs, and you will use it in 06-05.

Every object shares four top-level fields:

And now the most important thing in the whole lesson. In Kubernetes objects are not referenced by name, they are referenced by labels. A Service does not say "send traffic to the Pods of the aurora-api Deployment"; it says "send traffic to every Pod with the label app: aurora-api".

That loose coupling is both powerful and fragile. Powerful because it allows things like directing traffic to Pods from two different Deployments at once, which is the basis of the blue-green and canary deployments in 06-07. Fragile because a typo in a label produces no error at all: the Service simply finds no Pods, ends up with no endpoints and the traffic returns 503. It is the most common silent failure, and it is always diagnosed the same way: kubectl get endpoints <service>.

The labels recommended by the community, which are worth adopting from the start:

Two commands deserve highlighting. kubectl explain is the official documentation without leaving the terminal, and it works for any field of any object, including ones you install later. And kubectl describe ends with a list of events that almost always contains the exact cause of the problem: why the scheduler cannot find a node, why the image pull fails or why a probe is not passing.

• Creating standalone Pods. Nobody recreates them if the node dies. Except for a thirty-second test, always use a Deployment.
• A selector and labels that do not match. The most frequent and the most silent error: the Deployment creates Pods its Service cannot find. Check with kubectl get endpoints.
• Believing a Secret is encrypted. It is base64. Turn on encryption at rest and protect it with RBAC.
• Expecting an Ingress to work with no controller. The object gets created without complaint and routes nothing.
• Forgetting the namespace. kubectl get pods looks at the default namespace and it seems as if there is nothing there. Set the context or use -n.
• Defining limits without requests. Kubernetes copies the limit into the request and you reserve far more than you need.
• Editing Pods with kubectl edit. The change lasts until the next deployment. Modify the Deployment instead.
• Tip: kubectl describe before kubectl logs. If the Pod does not start, there are no logs; the cause is in the events.
• Tip: kubectl apply --dry-run=server -f . validates the manifests against the real API without creating anything. Use it in your pipeline.

Exercise 1. Set up a three-node kind cluster, deploy aurora-cache with a Deployment and its ClusterIP Service, and check from another Pod that the name aurora-cache resolves and responds.

Exercise 2. Demonstrate the reconciliation loop and the difference between a standalone Pod and a Deployment: create a Pod by hand and another managed by a Deployment, delete both and observe what happens to each.

Exercise 3. Trigger the silent label failure on purpose: change a Service's selector so it matches no Pod and diagnose it without looking at the manifest.

Solution 1.

A single output contains the whole chain from section 7: a Deployment that created a ReplicaSet whose name carries the suffix 6b8d4c9f7 —the hash of the Pod template—, and that ReplicaSet created a Pod that inherits the hash and adds a random suffix. That hash is the key piece of the rolling update: changing the image produces a different hash and therefore a new ReplicaSet.

The short name and the full one resolve to the same IP, which is the Service's virtual IP, not the Pod's. That distinction is what lets Pods die and be reborn with different addresses without anybody having to find out: the client always talks to the Service. It is the same service the internal DNS of Compose and Swarm gave you, with one important difference: here it is provided by an explicit object you can inspect and modify.

Solution 2.

You deleted two Pods and only one came back, with a different name and five seconds of age. The OWNER column explains exactly why: the standalone Pod has no ownerReferences, so when you deleted it nobody missed anything; the others belong to a ReplicaSet whose controller watches the API, saw it had one Pod where there should be two and created a new one.

That is the practical reason behind the rule in section 6. A standalone Pod is equivalent to a docker run with no restart policy: it survives as long as nothing bothers it, and it disappears along with its node. The detail of the different name matters too, because it reveals that the Pod is not "restarted": another one is created, with another IP, and that is why no configuration can depend on the identity of one specific Pod. When that identity is genuinely needed —as with aurora-db— there is the StatefulSet.

Solution 3.

The diagnosis, without opening a single file:

The ENDPOINTS reading <none> is the decisive symptom, and the three-command sequence is the one to memorize: the Service exists, it has its virtual IP, the DNS resolves perfectly... and there is not one Pod behind it. Comparing the selector (app=aurora-cach) with the actual labels (app=aurora-cache) reveals the missing letter.

What is instructive about the exercise is what did not happen: neither the kubectl patch nor the kubectl get svc nor the Deployment's describe gave the slightest warning. Kubernetes does not validate that a selector finds anything, because a Service that does not yet have Pods is a legitimate situation —it will have them once they are deployed. The price of that loose coupling, which in 06-07 will let you switch traffic between two versions by changing a label, is that a typo shows up as a 503 in production rather than as an error when applying the manifest.

Hence the operating rule: after every kubectl apply that touches a Service, check its endpoints. It is one command and it avoids the most frustrating class of incident on this platform.

You speak Kubernetes now. You know its heart is the same reconciliation loop as Swarm's, generalized to every object in etcd, and that this explains why a deleted Pod comes back and why a repeated apply does nothing. You know the architecture —kube-apiserver as the only door, etcd as the state, the scheduler, the controllers, and on every node the kubelet and the kube-proxy— and the property that makes it robust: nobody talks to anybody except the API. And you have the dockershim misunderstanding settled: Kubernetes runs containerd over CRI, but your images are just as valid because they are OCI.

You can handle the catalog of objects with their minimal YAML: the Pod as the unit and why you do not create one by hand, the Deployment → ReplicaSet → Pods chain where the empty ReplicaSet is your rollback history, the Service with its five variants and the Ingress that routes nothing without an installed controller, ConfigMap and Secret —with the warning that base64 is not encryption—, the Namespace, the PVC/PV/StorageClass triad with the access modes that will explain in 06-06 why a database cannot simply be replicated, and the four remaining controllers, among them the DaemonSet that is Swarm's mode: global and the StatefulSet that Swarm did not have.

Above all, you have internalized the central piece: labels and selectors. Everything connects by labels, never by name, and you proved it by breaking a selector on purpose to see the platform's most silent failure —a perfectly healthy Service with ENDPOINTS <none>— and diagnosing it with three commands. You can translate each Docker operation into its kubectl equivalent, you have a three-node kind cluster with aurora-cache running inside it, and a glossary that turns what you already knew into what you have just learned.

In the next lesson, Deploying Docker Containers in Kubernetes, the whole application arrives. You will write the real manifests for the four services: the StatefulSet for aurora-db with its volumeClaimTemplates and its headless Service, the Deployment for aurora-api with the three probes from 06-01, its hardened securityContext and its injected configuration, the Ingress for aurora-web, and you will organize them with Kustomize into bases and per-environment overlays, along with the table of Pod states —Pending, ImagePullBackOff, CrashLoopBackOff, OOMKilled— and the diagnostic command for each, ready for when something refuses to start.