The imperative kubectl create deployment from the last lesson was fine for a demo, and useless for a team. Nobody can review it, nobody knows what flags were used, and next week nobody can reproduce it. From here on, notes-api’s Kubernetes setup lives in YAML files under k8s/, next to the Dockerfile, reviewed like code.
A Pod is one or more containers that are scheduled together onto one node and share a network namespace (one IP, one localhost) and any volumes you declare. Most Pods have one main container. A second container is for something tightly coupled to the first, like a log shipper or a proxy that must live and die with it.
A minimal Pod manifest looks like this:
\napiVersion: v1\nkind: Pod\nmetadata:\n name: notes-api-test\nspec:\n containers:\n - name: api\n image: ghcr.io/skylane/notes-api:1.4.0\n ports:\n - containerPort: 3000You won’t create Pods like this in practice. A bare Pod isn’t replaced if it crashes on a dead node, can’t be scaled, and can’t be updated to a new image gradually. Pods are cattle: every one is disposable, gets a new name and IP when replaced, and is managed by something above it.
\nA Deployment is that something. It owns a ReplicaSet, whose only job is to keep N identical Pods running. The Deployment’s job is to manage ReplicaSets over time: when you change the Pod template, it creates a new ReplicaSet and shifts Pods over, which is the rolling update you’ll study in section 5.
\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: notes-api\n labels:\n app.kubernetes.io/name: notes-api\nspec:\n replicas: 3\n selector:\n matchLabels:\n app.kubernetes.io/name: notes-api\n template:\n metadata:\n labels:\n app.kubernetes.io/name: notes-api\n spec:\n containers:\n - name: api\n image: ghcr.io/skylane/notes-api:1.4.0\n ports:\n - name: http\n containerPort: 3000\n env:\n - name: PORT\n value: \"3000\"Read it in two halves. The top half is the Deployment itself: its name, how many replicas, and which Pods it owns (selector). Everything under template is a Pod spec, the blueprint each replica is stamped from. Note that apiVersion differs by kind: Pods are core v1, Deployments are apps/v1.
Kubernetes objects don’t point at each other by name. They find each other by labels, key-value pairs in metadata.labels, and selectors, queries over those labels. The ReplicaSet counts its Pods by running its selector; next lesson, a Service will find Pods to send traffic to the same way.
That’s why the Deployment’s selector.matchLabels must match template.metadata.labels: the Deployment must be able to find the Pods its own template creates. The API server checks this and rejects a mismatch. The selector is also immutable once the Deployment exists, so choose it carefully. The app.kubernetes.io/name key is one of Kubernetes’ recommended labels; tools and dashboards understand it, and using it consistently pays off.
kind load docker-image ghcr.io/skylane/notes-api:1.4.0 --name notes\nkubectl apply -f k8s/deployment.yaml\nkubectl get deploy,rs,pods -l app.kubernetes.io/name=notes-api\nkubectl describe deployment notes-apikind load copies the image into the cluster under its full name, so the manifest can use the same reference production will. -l filters by label, the same mechanism the controllers use. Look at the Pod names: notes-api-6c8f9d7b5-x2k4q is the Deployment name, then the ReplicaSet’s pod-template-hash, then a random suffix. Change anything in the template and you’ll get a new ReplicaSet with a new hash.
To scale, change replicas: 3 to 5 in the file and apply again. kubectl apply compares your file with what’s stored and sends only the difference. kubectl diff -f k8s/ shows that difference before you commit to it, and you should make a habit of running it.
kubectl scale deployment/notes-api --replicas=5 also works, and has its place in an emergency. But the file still says 3, so the next routine apply quietly scales you back down. Whatever you change by hand, change in Git straight after.
Your Pods are running, but each has its own IP that changes every time it’s replaced. Nothing can reliably reach them yet. That’s what Services are for.
\n","toc":[{"id":"sec-1","text":"Pods: the unit Kubernetes runs","level":2},{"id":"sec-2","text":"Deployments, ReplicaSets, Pods","level":2},{"id":"sec-3","text":"Labels and selectors","level":2},{"id":"sec-4","text":"Apply, inspect, scale","level":2}],"takeaways":["A Pod is one or more containers that share a network identity and storage; it’s the smallest thing Kubernetes schedules, and it’s disposable.","You almost never create bare Pods; a Deployment manages a ReplicaSet, which keeps the right number of Pods running.","A Deployment’sspec.selector.matchLabels must match the labels in spec.template.metadata.labels, and the selector can’t be changed after creation.","Keep manifests in Git and change them with kubectl apply -f, so the files stay the source of truth.","Use current API versions such as apps/v1; manifests copied from old posts with extensions/v1beta1 no longer work."],"further":[{"title":"Pods","url":"https://kubernetes.io/docs/concepts/workloads/pods/"},{"title":"Deployments","url":"https://kubernetes.io/docs/concepts/workloads/controllers/deployment/"},{"title":"Labels and Selectors","url":"https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/"},{"title":"Recommended Labels","url":"https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/"}],"quiz":[{"q":"Why run notes-api through a Deployment instead of creating three Pods directly?
","options":[{"text":"Pods can’t be created from YAML files.","why":"They can. A bare Pod manifest is valid; it’s just not managed by anything."},{"text":"Pods created directly can’t use container images from a registry.","why":"Image pulling works the same for any Pod. Management is the difference."},{"text":"Deployments run containers faster than bare Pods.","why":"Startup speed is identical. The containers run the same way."},{"text":"A bare Pod isn’t replaced if it or its node dies, and it can’t be rolled out to a new version gradually; a Deployment handles both.","why":"Correct. The Deployment, through its ReplicaSet, keeps the count right and manages updates."}],"answer":3},{"q":"kubectl apply rejects a Deployment with: selector does not match template labels. What’s wrong?
spec.selector.matchLabels asks for labels that spec.template.metadata.labels doesn’t set.","why":"Correct. The Deployment must be able to find the Pods its own template creates, so the API server validates that they match."},{"text":"The Deployment is in a different namespace from its Pods.","why":"A Deployment’s Pods are always created in its own namespace."},{"text":"The image tag isn’t a valid label value.","why":"The image isn’t a label at all; it doesn’t take part in selection."}],"answer":1},{"q":"You run kubectl get pods and see notes-api-6c8f9d7b5-x2k4q. What is 6c8f9d7b5?
kubectl get pods -o wide to see nodes."},{"text":"A hash of the Pod template, identifying the ReplicaSet that created this Pod.","why":"Correct. Each template version gets its own ReplicaSet, and its Pods carry its pod-template-hash. You’ll see why this matters for rollbacks."},{"text":"A random suffix with no meaning.","why":"Only the last part (x2k4q) is random. The middle part is deliberate."}],"answer":2},{"q":"Someone ran kubectl scale deployment/notes-api --replicas=6 during an incident. What happens at the next kubectl apply -f k8s/ with replicas set to 3 in the file?
A teammate adapted this Deployment from a blog post. kubectl apply fails, and after fixing the first error it fails again with a different one. Select the two lines to fix.
Line 1 uses extensions/v1beta1, which was removed long ago; apply fails with no matches for kind "Deployment". Use apps/v1.
Line 13 labels the Pods notes, but the selector asks for notes-api, so the API server rejects the Deployment because its selector doesn’t match its own template. Make them identical:
apiVersion: apps/v1\n# …\n selector:\n matchLabels:\n app.kubernetes.io/name: notes-api\n template:\n metadata:\n labels:\n app.kubernetes.io/name: notes-api