Kubernetes Pods, Deployments, and Services in YAML

The manifest below declares both objects in one file, separated by --- (a standard multi-document YAML separator). Save it as web.yaml. A Deployment manifest has four parts worth understanding line by line:

• apiVersion: apps/v1 and kind: Deployment, which API group and object type you are declaring. Deployments live in the apps group, not the core v1 group.
• spec.replicas: 3, the desired state. The ReplicaSet controller will create pods until three are running, and recreate any that die.
• spec.selector.matchLabels, how the Deployment knows which pods belong to it. This must match spec.template.metadata.labels exactly, or the API server rejects the manifest.
• spec.template, the pod blueprint. Every pod the ReplicaSet creates is stamped from this template, including the pinned image nginx:1.25.

# web.yaml
apiVersion: apps/v1
kind: Deployment
metadata: { name: web }
spec:
  replicas: 3
  selector: { matchLabels: { app: web } }
  template:
    metadata: { labels: { app: web } }
    spec:
      containers:
        - name: web
          image: nginx:1.25
---
apiVersion: v1
kind: Service
metadata: { name: web }
spec:
  selector: { app: web }
  ports: [{ port: 80 }]

Expected output:

$ kubectl apply --dry-run=client -f web.yaml
deployment.apps/web created (dry run)
service/web created (dry run)

The Service is deliberately minimal: selector: { app: web } tells it to send traffic to every pod carrying that label, and port: 80 is the port the Service itself listens on. Because no type is given, it defaults to ClusterIP, reachable only from inside the cluster. No targetPort is set either, so traffic is forwarded to the same port number (80) on the pods, which is where nginx listens by default.

Common mistake: writing the Service selector as app: web-svc or the pod label as app: frontend "to be descriptive". The objects are wired together purely by these strings, they must match character for character. If you are ever unsure of a field, kubectl explain deployment.spec.template prints the API documentation for any field path.

Finally, validate the file before it ever touches the cluster. A client-side dry run catches schema errors (bad indentation, a wrong apiVersion) instantly, and once the objects exist, kubectl diff previews exactly what a future apply would change:

What this teaches: The manifest is the application as data; Deployment plus Service is the smallest complete shippable unit.

kubectl apply is declarative: it diffs your file against the live state and makes only the changes needed. Re-running it with an unchanged file is a no-op, which is why it, not kubectl create, is the command you script and commit to CI. Follow it immediately with rollout status, which blocks until all replicas are updated and ready, so your terminal prompt returning means the deployment actually succeeded.

Now verify what was actually created. You should see three running pods (each with a random suffix, the first chunk is the ReplicaSet hash, the second the pod hash) and a Service with a cluster-internal IP:

The endpoints output is the proof that the label wiring works: the Service's virtual IP 10.96.143.21 is backed by exactly the three pod IPs from the first command. If the endpoints list were <none>, the selector does not match any pod labels.

The Deployment's own status row is the compact summary operators watch:

UP-TO-DATE counts pods running the latest template revision; AVAILABLE counts pods passing readiness (with no probes defined, that simply means "container started"). During a rollout these two columns briefly disagree, that gap is the update in progress.

How to verify: READY 1/1 on all three pods, the rollout status line "successfully rolled out", and three IPs in the endpoints list. All three must be true before moving on.

Expected output:

$ kubectl apply -f web.yaml
deployment.apps/web created
service/web created

What this teaches: Apply is the only deployment verb you need; it creates or updates toward the declared state.

Now simulate shipping a new release: bump nginx from 1.25 to 1.27. kubectl set image patches the Deployment's pod template (the container name before the = must match the name: web in your manifest). Changing the template triggers the Deployment's default update strategy, RollingUpdate: it creates a new ReplicaSet for nginx:1.27, scales it up one pod at a time, and only scales an old pod down once a new one is Ready. With the defaults maxSurge: 25% and maxUnavailable: 25%, the Service always has healthy pods behind it, that is what makes the update zero-downtime for containers that report ready promptly. A readiness probe is what lets Kubernetes hold traffic until the new container actually serves, add one before relying on this in production.

To watch the swap happen in real time, open a second terminal before running the update and stream the pod list:

Catch the rollout mid-flight and the ReplicaSet view tells the whole story, the old ReplicaSet scaling down while the new one scales up:

Each ReplicaSet name embeds a hash of its pod template, which is how the Deployment tells revisions apart. When the rollout completes, the old ReplicaSet sits at 0 replicas but is kept around, it becomes your rollback target in step 04.

Every template change is recorded as a numbered revision. This history is what makes the next step possible:

Common mistake: the CHANGE-CAUSE column shows <none> because nothing recorded why the change happened. On real projects annotate each release so the history is self-documenting: kubectl annotate deploy/web kubernetes.io/change-cause="bump nginx 1.25 to 1.27". Also note the image tag is explicit (1.27, not latest), with latest the pod template hash does not change, so no rollout is triggered at all.

How to verify: kubectl get deploy web -o jsonpath='{.spec.template.spec.containers[0].image}' should print nginx:1.27, and kubectl get rs should show two ReplicaSets, the new one at 3 replicas, the old one scaled to 0 but retained for rollback.

Expected output:

$ kubectl set image deploy/web web=nginx:1.27
deployment.apps/web image updated
$ kubectl rollout status deploy/web
deployment "web" successfully rolled out

What this teaches: Rolling out a new image is changing one field and letting the controllers converge; watch the ReplicaSets trade places.

Pretend the 1.27 release introduced a regression and you need to revert now. Because the old ReplicaSet was scaled to zero rather than deleted, a rollback is just a pointer flip: the Deployment scales the previous ReplicaSet back up and the new one down. It is the same rolling mechanism in reverse, so it is also zero-downtime under the same readiness conditions.

That reverts to the immediately previous revision. To jump to a specific older revision, pick its number from the history:

One subtlety: a rollback does not erase history, it creates a new revision whose template is a copy of the one you reverted to. After the undo, kubectl rollout history shows revision 3 with the nginx:1.25 template, revisions only ever move forward.

Revision 1 disappeared from the list because its template now lives at revision 3, Kubernetes renumbers the newest copy rather than resurrecting the old slot. The change-cause annotation habit from step 03 is what keeps this list meaningful on a real project.

How to verify: the image is back to nginx:1.25, all pods show Running, and kubectl get endpoints web still lists three healthy IPs. In a real incident you would then curl the Service (next section) to confirm the app itself, not just the pods, is healthy.

Expected output:

$ kubectl rollout undo deploy/web
deployment.apps/web rolled back

What this teaches: Rollback scales the previous ReplicaSet back up; it is fast because the old pods' definition never left etcd.