Specimen No. 1483 · Habitat H4 · DevOps & IT

Kubernetes from Zero · Foundations 7 of 12 · Lesson 7

Kubernetes from Zero, part 7: Deployments and ReplicaSets

Run Pods through a Deployment: self-healing, scaling, a rolling update with maxSurge and maxUnavailable, a stuck rollout and a rollback, all tested on kind.

WILDNESS1 / 5 · TAMED
Verified: Every command ran on a kind v0.33.0 cluster (node v1.37.0, kubectl v1.37.2) on 10 Nov 2026Only claimed: Defaults for maxSurge, maxUnavailable, progressDeadlineSeconds and history come from the Kubernetes docs
Five cut-paper sailboats ride layered blue paper waves; the one on the left has a coral sail and the other four cream sails, with a slate-blue ship's wheel above them.
Generated cover art. Not a photo.

In part 6 you organised a cluster with namespaces and labels. The Pods you have made so far were single, hand-made objects: delete one and it stays gone. This episode hands Pods to a controller. By the end you will run three copies of a web server through a Deployment, watch Kubernetes replace a Pod you delete, scale up and down, roll out a new image without downtime, break a release on purpose and roll it back. You need the kind cluster from part 3 and the k8s-from-zero namespace from part 4, with your context namespace set to it as in part 6. We tested on kind v0.33.0 (node image v1.37.0) with kubectl v1.37.2.

What you will build

You will write one Deployment called web that asks for three nginx Pods. You will then look at the two layers Kubernetes builds under it, a ReplicaSet and its Pods, and follow how the layers point to each other. After that you will change the image twice, once correctly and once with a typo, and use kubectl rollout to watch, inspect and undo those changes.

A Deployment named web owns two ReplicaSets: the current one, web-86f79b74d9, owns three running Pods, and the old one, web-55dd75b68d, sits at 0 replicas for rollback. The pod-template-hash label, highlighted, links the current ReplicaSet to its Pods.

A Deployment manages ReplicaSets, which manage Pods

A ReplicaSet has one job: keep a stated number of Pods that match its label selector running. If there are too few, it creates Pods from its Pod template. If there are too many, it deletes some. That is the self-healing loop from part 1, applied to Pods.

A Deployment sits one level up. The Deployments page describes it as providing declarative updates for Pods and ReplicaSets. You never create the ReplicaSet yourself. The Deployment creates one for each version of the Pod template, and moves Pods from the old one to the new one at a controlled rate when you change the template. The docs say plainly: do not manage ReplicaSets owned by a Deployment.

A Deployment manifest adds three things to the Pod you already know:

  • replicas: how many Pods you want. It defaults to 1.
  • selector: which Pods belong to this Deployment, by label. It must match the template’s labels, and it cannot be changed after creation.
  • template: a Pod spec without apiVersion and kind. Every Pod the Deployment makes is stamped from it.

Each layer records who owns it in metadata.ownerReferences (owners and dependents). A Pod points to its ReplicaSet, and a ReplicaSet points to its Deployment. When you delete the Deployment, the garbage collector follows those references and deletes everything below it.

The Deployment controller also adds a label, pod-template-hash, to each ReplicaSet and its Pods. Its value is a hash of the Pod template, which is why ReplicaSet and Pod names look like web-86f79b74d9-4jvbj: Deployment name, template hash, random suffix. The docs warn you not to change that label.

A rolling update swaps ReplicaSets a few Pods at a time

A rollout starts when, and only when, you change the Pod template (.spec.template): a new image, a new label in the template, a new environment variable. Changing replicas scales the current ReplicaSet and starts no rollout.

With the default strategy, RollingUpdate, the Deployment creates a new ReplicaSet and grows it while shrinking the old one. Two fields set the pace:

  • maxSurge: how many Pods may exist above replicas during the update. Default 25%, rounded up.
  • maxUnavailable: how many Pods may be unavailable during the update. Default 25%, rounded down.

They cannot both be 0. Our lab uses maxSurge: 1 and maxUnavailable: 0: add one new Pod, wait until it is ready, remove one old Pod, repeat. Capacity never drops, at the cost of one extra Pod while the update runs.

Five rows show our rollout from nginx 1.28 to 1.29 with replicas 3, maxSurge 1 and maxUnavailable 0: three old Pods, then a fourth new surge Pod, then one old Pod swapped for a new one at a time, until three new Pods remain. A highlighted note says available Pods never drop below 3.

The other strategy, Recreate, deletes all old Pods before creating any new ones. Use it only when two versions must never run at the same time, and accept the gap in service.

“Ready” matters here. Right now a Pod counts as ready as soon as its container starts. Part 10 adds readiness probes so that a Pod only counts once it actually answers, which makes rolling updates much safer.

Rollout history lives in old ReplicaSets

The Deployment keeps old ReplicaSets, scaled to 0, so it can go back. Each one is a revision. .spec.revisionHistoryLimit sets how many old ReplicaSets to keep, 10 by default. The CHANGE-CAUSE column in kubectl rollout history is copied from the Deployment’s kubernetes.io/change-cause annotation when the revision is created, so put a short reason there in your file. The old --record flag that used to fill it is deprecated.

kubectl rollout undo copies an older Pod template back into the Deployment, which starts a normal rollout and records a new revision number. You will see that in step 9.

Try it: run, scale, update and roll back

  1. Let kubectl draft the YAML (part 5 showed this trick):
bash
kubectl create deployment demo --image=nginx:1.29-alpine --replicas=2 --dry-run=client -o yaml

Explain this command

kubectl create deployment demo --image=nginx:1.29-alpine --replicas=2 --dry-run=client -o yaml
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. create Create a resource from a file or from stdin, or through a subcommand such as namespace.
  3. deployment The resource type.
  4. demo The object name.
  5. --image=nginx:1.29-alpine The image for the container to run. The lesson pins the tag nginx:1.29-alpine.
  6. --replicas=2 The number of desired replicas. This command passes 2.
  7. --dry-run=client A dry run. The run docs say --dry-run must be none, server, or client. Client only prints the object that would be sent, without sending it. The lesson uses client dry-run to write YAML.
  8. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  9. yaml An output format. It prints the object as YAML.
Explain this command
kubectl create deployment demo --image=nginx:1.29-alpine --replicas=2 --dry-run=client -o yaml
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. create Create a resource from a file or from stdin, or through a subcommand such as namespace.
  3. deployment The resource type.
  4. demo The object name.
  5. --image=nginx:1.29-alpine The image for the container to run. The lesson pins the tag nginx:1.29-alpine.
  6. --replicas=2 The number of desired replicas. This command passes 2.
  7. --dry-run=client A dry run. The run docs say --dry-run must be none, server, or client. Client only prints the object that would be sent, without sending it. The lesson uses client dry-run to write YAML.
  8. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  9. yaml An output format. It prints the object as YAML.
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: demo
  name: demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: demo
  strategy: {}
  template:
    metadata:
      labels:
        app: demo
...

The selector and the template labels match. That is the one rule you must keep when you write your own.

  1. Write the Deployment. Save as web.yaml. We start on nginx 1.28 so there is something to upgrade to.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: k8s-from-zero
  labels:
    app.kubernetes.io/name: web
  annotations:
    kubernetes.io/change-cause: "first release, nginx 1.28"
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app.kubernetes.io/name: web   # must match the selector
    spec:
      containers:
        - name: web
          image: nginx:1.28-alpine
          ports:
            - containerPort: 80
bash
kubectl apply -f web.yaml
kubectl rollout status deployment/web --timeout=90s

Explain this command

kubectl apply -f web.yaml
kubectl rollout status deployment/web --timeout=90s
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=90s How long to wait before giving up. This command passes 90s.
Explain this command
kubectl apply -f web.yaml
kubectl rollout status deployment/web --timeout=90s
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=90s How long to wait before giving up. This command passes 90s.
deployment.apps/web created
Waiting for deployment "web" rollout to finish: 0 of 3 updated replicas are available...
Waiting for deployment "web" rollout to finish: 1 of 3 updated replicas are available...
Waiting for deployment "web" rollout to finish: 2 of 3 updated replicas are available...
deployment "web" successfully rolled out

rollout status waits and exits 0 when the rollout is complete. It is the command to put in a deploy script.

  1. Look at the three layers.
bash
kubectl get deployment web
kubectl get replicasets
kubectl get pods --show-labels

Explain this command

kubectl get deployment web
kubectl get replicasets
kubectl get pods --show-labels
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  3. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  4. web The object name.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. replicasets The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  8. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  9. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  10. pods The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  11. --show-labels When printing, show all labels as the last column. The get docs say that column is hidden by default.
Explain this command
kubectl get deployment web
kubectl get replicasets
kubectl get pods --show-labels
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  3. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  4. web The object name.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. replicasets The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  8. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  9. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  10. pods The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  11. --show-labels When printing, show all labels as the last column. The get docs say that column is hidden by default.
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    3/3     3            3           1s
NAME             DESIRED   CURRENT   READY   AGE
web-55dd75b68d   3         3         3       1s
NAME                   READY   STATUS    RESTARTS   AGE   LABELS
web-55dd75b68d-5vtbs   1/1     Running   0          1s    app.kubernetes.io/name=web,pod-template-hash=55dd75b68d
web-55dd75b68d-hcvdc   1/1     Running   0          1s    app.kubernetes.io/name=web,pod-template-hash=55dd75b68d
web-55dd75b68d-xrpx6   1/1     Running   0          1s    app.kubernetes.io/name=web,pod-template-hash=55dd75b68d

Your hash and suffixes will differ. UP-TO-DATE counts Pods on the current template; AVAILABLE counts Pods that are ready.

  1. Follow the owner references with custom columns (part 5):
bash
kubectl get pod -l app.kubernetes.io/name=web -o custom-columns=POD:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name
kubectl get rs -l app.kubernetes.io/name=web -o custom-columns=RS:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name

Explain this command

kubectl get pod -l app.kubernetes.io/name=web -o custom-columns=POD:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name
kubectl get rs -l app.kubernetes.io/name=web -o custom-columns=RS:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  3. pod The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  4. -l Short form of --selector. A label query. The get docs say it supports '=', '==', '!=', 'in' and 'notin', and that matching objects must satisfy every constraint.
  5. app.kubernetes.io/name=web The label query passed to --selector: app.kubernetes.io/name=web.
  6. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  7. custom-columns=POD:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name custom-columns is an output format. The get examples write each column as a heading, a colon, and a JSONPath. The headings here are POD, OWNER-KIND, OWNER.
  8. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  9. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  10. rs The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  11. -l Short form of --selector. A label query. The get docs say it supports '=', '==', '!=', 'in' and 'notin', and that matching objects must satisfy every constraint.
  12. app.kubernetes.io/name=web The label query passed to --selector: app.kubernetes.io/name=web.
  13. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  14. custom-columns=RS:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name custom-columns is an output format. The get examples write each column as a heading, a colon, and a JSONPath. The headings here are RS, OWNER-KIND, OWNER.
Explain this command
kubectl get pod -l app.kubernetes.io/name=web -o custom-columns=POD:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name
kubectl get rs -l app.kubernetes.io/name=web -o custom-columns=RS:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  3. pod The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  4. -l Short form of --selector. A label query. The get docs say it supports '=', '==', '!=', 'in' and 'notin', and that matching objects must satisfy every constraint.
  5. app.kubernetes.io/name=web The label query passed to --selector: app.kubernetes.io/name=web.
  6. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  7. custom-columns=POD:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name custom-columns is an output format. The get examples write each column as a heading, a colon, and a JSONPath. The headings here are POD, OWNER-KIND, OWNER.
  8. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  9. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  10. rs The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  11. -l Short form of --selector. A label query. The get docs say it supports '=', '==', '!=', 'in' and 'notin', and that matching objects must satisfy every constraint.
  12. app.kubernetes.io/name=web The label query passed to --selector: app.kubernetes.io/name=web.
  13. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  14. custom-columns=RS:.metadata.name,OWNER-KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name custom-columns is an output format. The get examples write each column as a heading, a colon, and a JSONPath. The headings here are RS, OWNER-KIND, OWNER.
POD                    OWNER-KIND   OWNER
web-55dd75b68d-5vtbs   ReplicaSet   web-55dd75b68d
web-55dd75b68d-hcvdc   ReplicaSet   web-55dd75b68d
web-55dd75b68d-xrpx6   ReplicaSet   web-55dd75b68d
RS               OWNER-KIND   OWNER
web-55dd75b68d   Deployment   web
  1. Delete a Pod and watch it come back. Use one of your own Pod names.
bash
kubectl delete pod web-55dd75b68d-5vtbs
kubectl get pods

Explain this command

kubectl delete pod web-55dd75b68d-5vtbs
kubectl get pods
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. delete Delete resources by file names, stdin, resources and names, or by resources and label selector.
  3. pod The resource type.
  4. web-55dd75b68d-5vtbs The object name.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. pods The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
Explain this command
kubectl delete pod web-55dd75b68d-5vtbs
kubectl get pods
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. delete Delete resources by file names, stdin, resources and names, or by resources and label selector.
  3. pod The resource type.
  4. web-55dd75b68d-5vtbs The object name.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. pods The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
pod "web-55dd75b68d-5vtbs" deleted from k8s-from-zero namespace
NAME                   READY   STATUS    RESTARTS   AGE
web-55dd75b68d-hcvdc   1/1     Running   0          8s
web-55dd75b68d-xrpx6   1/1     Running   0          8s
web-55dd75b68d-xtt58   1/1     Running   0          1s

A new Pod, one second old, took its place. The ReplicaSet’s events say who did it:

bash
kubectl describe rs web-55dd75b68d | tail -6

Explain this command

kubectl describe rs web-55dd75b68d | tail -6
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. describe Show details of a specific resource or group of resources. The describe docs say this includes related resources such as events or controllers.
  3. rs The resource type.
  4. web-55dd75b68d The object name.
  5. | Shell. Sends the previous command's standard output to the next command.
  6. tail Shell. Prints the end of its input.
  7. -6 The line count on tail. The lesson keeps the last 6 lines, the ReplicaSet events that name the replicaset-controller.
Explain this command
kubectl describe rs web-55dd75b68d | tail -6
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. describe Show details of a specific resource or group of resources. The describe docs say this includes related resources such as events or controllers.
  3. rs The resource type.
  4. web-55dd75b68d The object name.
  5. | Shell. Sends the previous command's standard output to the next command.
  6. tail Shell. Prints the end of its input.
  7. -6 The line count on tail. The lesson keeps the last 6 lines, the ReplicaSet events that name the replicaset-controller.
  Type    Reason            Age   From                   Message
  ----    ------            ----  ----                   -------
  Normal  SuccessfulCreate  8s    replicaset-controller  Created pod: web-55dd75b68d-5vtbs
  Normal  SuccessfulCreate  8s    replicaset-controller  Created pod: web-55dd75b68d-xrpx6
  Normal  SuccessfulCreate  8s    replicaset-controller  Created pod: web-55dd75b68d-hcvdc
  Normal  SuccessfulCreate  1s    replicaset-controller  Created pod: web-55dd75b68d-xtt58
  1. Scale, then let the file win.
bash
kubectl scale deployment web --replicas=5
kubectl get deployment web

Explain this command

kubectl scale deployment web --replicas=5
kubectl get deployment web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. scale Set a new size for a deployment, replica set, replication controller, or stateful set.
  3. deployment The resource type.
  4. web The object name.
  5. --replicas=5 The number of desired replicas. This command passes 5.
  6. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  7. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  8. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  9. web The object name.
Explain this command
kubectl scale deployment web --replicas=5
kubectl get deployment web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. scale Set a new size for a deployment, replica set, replication controller, or stateful set.
  3. deployment The resource type.
  4. web The object name.
  5. --replicas=5 The number of desired replicas. This command passes 5.
  6. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  7. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  8. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  9. web The object name.
deployment.apps/web scaled
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    5/5     5            5           22s

Now apply the file again, which still says replicas: 3:

bash
kubectl apply -f web.yaml
kubectl get deployment web

Explain this command

kubectl apply -f web.yaml
kubectl get deployment web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  8. web The object name.
Explain this command
kubectl apply -f web.yaml
kubectl get deployment web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  8. web The object name.
deployment.apps/web configured
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    3/3     3            3           27s

The docs warn about exactly this: applying a manifest overwrites a manual scale. Change the number in the file if you want it to last. (When an autoscaler owns the count, part 25 shows you leave replicas out of the file.)

  1. Roll out nginx 1.29. Copy web.yaml to web-v2.yaml and change two lines:
bash
diff web.yaml web-v2.yaml

Explain this command

diff web.yaml web-v2.yaml
  1. diff Compares inputs line by line.
  2. web.yaml The first file diff compares (from-file): the nginx 1.28 manifest.
  3. web-v2.yaml The second file diff compares (to-file): the nginx 1.29 manifest.
Explain this command
diff web.yaml web-v2.yaml
  1. diff Compares inputs line by line.
  2. web.yaml The first file diff compares (from-file): the nginx 1.28 manifest.
  3. web-v2.yaml The second file diff compares (to-file): the nginx 1.29 manifest.
9c9
<     kubernetes.io/change-cause: "first release, nginx 1.28"
---
>     kubernetes.io/change-cause: "upgrade to nginx 1.29"
27c27
<           image: nginx:1.28-alpine
---
>           image: nginx:1.29-alpine

In a second terminal, start a watch on the ReplicaSets with kubectl get rs -l app.kubernetes.io/name=web --watch. Then apply:

bash
kubectl apply -f web-v2.yaml
kubectl rollout status deployment/web --timeout=90s

Explain this command

kubectl apply -f web-v2.yaml
kubectl rollout status deployment/web --timeout=90s
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web-v2.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=90s How long to wait before giving up. This command passes 90s.
Explain this command
kubectl apply -f web-v2.yaml
kubectl rollout status deployment/web --timeout=90s
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web-v2.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=90s How long to wait before giving up. This command passes 90s.
deployment.apps/web configured
Waiting for deployment "web" rollout to finish: 1 out of 3 new replicas have been updated...
...
Waiting for deployment "web" rollout to finish: 2 out of 3 new replicas have been updated...
...
Waiting for deployment "web" rollout to finish: 1 old replicas are pending termination...
...
deployment "web" successfully rolled out

The watch shows the swap line by line (trimmed; columns are DESIRED, CURRENT, READY):

NAME             DESIRED   CURRENT   READY   AGE
web-55dd75b68d   3         3         3       33s
web-86f79b74d9   1         0         0       0s
...
web-86f79b74d9   1         1         1       1s
web-55dd75b68d   2         3         3       35s
...
web-86f79b74d9   2         2         2       1s
...
web-55dd75b68d   1         2         2       35s
...
web-86f79b74d9   3         3         3       2s
...
web-55dd75b68d   0         0         0       36s

The Deployment’s events tell the same story in words:

bash
kubectl describe deployment web | sed -n '/^Events:/,$p'

Explain this command

kubectl describe deployment web | sed -n '/^Events:/,$p'
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. describe Show details of a specific resource or group of resources. The describe docs say this includes related resources such as events or controllers.
  3. deployment The resource type.
  4. web The object name.
  5. | Shell. Sends the previous command's standard output to the next command.
  6. sed The stream editor. Here it filters the describe output down to the Events section.
  7. -n sed's -n: it turns off sed's automatic printing, so sed prints only the lines the script tells it to print with p.
  8. '/^Events:/,$p' The sed script, in single quotes. The range runs from the line that starts with Events: to the last line ($), and p prints it.
Explain this command
kubectl describe deployment web | sed -n '/^Events:/,$p'
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. describe Show details of a specific resource or group of resources. The describe docs say this includes related resources such as events or controllers.
  3. deployment The resource type.
  4. web The object name.
  5. | Shell. Sends the previous command's standard output to the next command.
  6. sed The stream editor. Here it filters the describe output down to the Events section.
  7. -n sed's -n: it turns off sed's automatic printing, so sed prints only the lines the script tells it to print with p.
  8. '/^Events:/,$p' The sed script, in single quotes. The range runs from the line that starts with Events: to the last line ($), and p prints it.
...
  Normal  ScalingReplicaSet  27s                deployment-controller  Scaled up replica set web-86f79b74d9 from 0 to 1
  Normal  ScalingReplicaSet  26s                deployment-controller  Scaled down replica set web-55dd75b68d from 3 to 2
  Normal  ScalingReplicaSet  26s                deployment-controller  Scaled up replica set web-86f79b74d9 from 1 to 2
  Normal  ScalingReplicaSet  26s                deployment-controller  Scaled down replica set web-55dd75b68d from 2 to 1
  Normal  ScalingReplicaSet  26s                deployment-controller  Scaled up replica set web-86f79b74d9 from 2 to 3
  Normal  ScalingReplicaSet  25s                deployment-controller  Scaled down replica set web-55dd75b68d from 1 to 0
bash
kubectl get rs
kubectl rollout history deployment/web

Explain this command

kubectl get rs
kubectl rollout history deployment/web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  3. rs The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  4. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  5. rollout The command group for rollout actions.
  6. history View previous rollouts.
  7. deployment/web The resource written as type/name: deployment/web.
Explain this command
kubectl get rs
kubectl rollout history deployment/web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  3. rs The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  4. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  5. rollout The command group for rollout actions.
  6. history View previous rollouts.
  7. deployment/web The resource written as type/name: deployment/web.
NAME             DESIRED   CURRENT   READY   AGE
web-55dd75b68d   0         0         0       61s
web-86f79b74d9   3         3         3       27s
deployment.apps/web 
REVISION  CHANGE-CAUSE
1         first release, nginx 1.28
2         upgrade to nginx 1.29

The old ReplicaSet is still there at 0. That is revision 1.

  1. Ship a typo. Save web-v3.yaml from web-v2.yaml with a misspelled tag, a new change-cause, and a short progress deadline so you do not wait the default 600 seconds:
bash
diff web-v2.yaml web-v3.yaml

Explain this command

diff web-v2.yaml web-v3.yaml
  1. diff Compares inputs line by line.
  2. web-v2.yaml The first file diff compares (from-file): the last good manifest.
  3. web-v3.yaml The second file diff compares (to-file): the manifest with the misspelled tag.
Explain this command
diff web-v2.yaml web-v3.yaml
  1. diff Compares inputs line by line.
  2. web-v2.yaml The first file diff compares (from-file): the last good manifest.
  3. web-v3.yaml The second file diff compares (to-file): the manifest with the misspelled tag.
9c9
<     kubernetes.io/change-cause: "upgrade to nginx 1.29"
---
>     kubernetes.io/change-cause: "typo release"
11a12
>   progressDeadlineSeconds: 30
27c28
<           image: nginx:1.29-alpine
---
>           image: nginx:1.29-alpne
bash
kubectl apply -f web-v3.yaml
kubectl rollout status deployment/web --timeout=20s
kubectl get pods
kubectl get deployment web

Explain this command

kubectl apply -f web-v3.yaml
kubectl rollout status deployment/web --timeout=20s
kubectl get pods
kubectl get deployment web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web-v3.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=20s How long to wait before giving up. This command passes 20s.
  10. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  11. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  12. pods The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  13. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  14. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  15. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  16. web The object name.
Explain this command
kubectl apply -f web-v3.yaml
kubectl rollout status deployment/web --timeout=20s
kubectl get pods
kubectl get deployment web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web-v3.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=20s How long to wait before giving up. This command passes 20s.
  10. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  11. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  12. pods The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  13. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  14. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  15. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  16. web The object name.
deployment.apps/web configured
Waiting for deployment "web" rollout to finish: 1 out of 3 new replicas have been updated...
error: timed out waiting for the condition
NAME                   READY   STATUS              RESTARTS   AGE
web-76798cdcf8-lrhdr   0/1     ContainerCreating   0          20s
web-86f79b74d9-4jvbj   1/1     Running             0          56s
web-86f79b74d9-fcr2z   1/1     Running             0          56s
web-86f79b74d9-qzjcc   1/1     Running             0          57s
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    3/3     3            3           92s

The new Pod cannot start: its image does not exist. On a normal network it shows ErrImagePull and then ImagePullBackOff within seconds; on our lab box, where the cluster has no internet, it sat in ContainerCreating while the pull timed out. Either way, the three old Pods kept serving, because maxUnavailable: 0 forbids removing them before a new Pod is ready. The rollout is stuck, and the app is fine.

After 30 seconds the Deployment reports it:

bash
kubectl rollout status deployment/web
kubectl get deployment web -o jsonpath='{range .status.conditions[*]}{.type}{"  "}{.status}{"  "}{.reason}{"\n"}{end}'

Explain this command

kubectl rollout status deployment/web
kubectl get deployment web -o jsonpath='{range .status.conditions[*]}{.type}{"  "}{.status}{"  "}{.reason}{"\n"}{end}'
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. rollout The command group for rollout actions.
  3. status Show the status of a rollout and wait until it finishes.
  4. deployment/web The resource written as type/name: deployment/web.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  8. web The object name.
  9. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  10. jsonpath='{range .status.conditions[*]}{.type}{" "}{.status}{" "}{.reason}{"\n"}{end}' jsonpath is an output format. A template is JSONPath expressions in curly braces. The JSONPath page says a double-quoted string inserts text, and its example uses a quoted backslash-n for a newline. This token is the template in the lesson command.
Explain this command
kubectl rollout status deployment/web
kubectl get deployment web -o jsonpath='{range .status.conditions[*]}{.type}{"  "}{.status}{"  "}{.reason}{"\n"}{end}'
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. rollout The command group for rollout actions.
  3. status Show the status of a rollout and wait until it finishes.
  4. deployment/web The resource written as type/name: deployment/web.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  8. web The object name.
  9. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  10. jsonpath='{range .status.conditions[*]}{.type}{" "}{.status}{" "}{.reason}{"\n"}{end}' jsonpath is an output format. A template is JSONPath expressions in curly braces. The JSONPath page says a double-quoted string inserts text, and its example uses a quoted backslash-n for a newline. This token is the template in the lesson command.
error: deployment "web" exceeded its progress deadline
Available  True  MinimumReplicasAvailable
Progressing  False  ProgressDeadlineExceeded

Kubernetes does nothing else about a stalled rollout; it only reports it. Rolling back is your job, or your CD tool’s.

  1. Roll back.
bash
kubectl rollout undo deployment/web
kubectl rollout status deployment/web --timeout=60s
kubectl rollout history deployment/web

Explain this command

kubectl rollout undo deployment/web
kubectl rollout status deployment/web --timeout=60s
kubectl rollout history deployment/web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. rollout The command group for rollout actions.
  3. undo Undo a rollout. By default it returns to the previous revision.
  4. deployment/web The resource written as type/name: deployment/web.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=60s How long to wait before giving up. This command passes 60s.
  10. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  11. rollout The command group for rollout actions.
  12. history View previous rollouts.
  13. deployment/web The resource written as type/name: deployment/web.
Explain this command
kubectl rollout undo deployment/web
kubectl rollout status deployment/web --timeout=60s
kubectl rollout history deployment/web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. rollout The command group for rollout actions.
  3. undo Undo a rollout. By default it returns to the previous revision.
  4. deployment/web The resource written as type/name: deployment/web.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=60s How long to wait before giving up. This command passes 60s.
  10. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  11. rollout The command group for rollout actions.
  12. history View previous rollouts.
  13. deployment/web The resource written as type/name: deployment/web.
Warning: resource deployments/web was previously managed with 'kubectl apply'. Rolling back will not update the kubectl.kubernetes.io/last-applied-configuration annotation, which may cause unexpected behavior on future 'kubectl apply' operations. Consider using 'kubectl apply' with your previous configuration file instead.
deployment.apps/web rolled back
Waiting for deployment spec update to be observed...
Waiting for deployment "web" rollout to finish: 1 old replicas are pending termination...
deployment "web" successfully rolled out
deployment.apps/web 
REVISION  CHANGE-CAUSE
1         first release, nginx 1.28
3         typo release
4         upgrade to nginx 1.29

Two things to notice. Revision 2 became revision 4: undo is a new rollout with an old template. And kubectl warns you that the Deployment now differs from the last file you applied (part 5 explained last-applied-configuration). In a team, the cleaner fix is the one the warning suggests: put the good image back in the file and kubectl apply it. Use undo when you need the service back first and the file fixed second.

You can also go back to a specific revision. Check what it holds first:

bash
kubectl rollout history deployment/web --revision=4 | grep -E "Image|change-cause"
kubectl rollout undo deployment/web --to-revision=1
kubectl get deployment web -o jsonpath="{.spec.template.spec.containers[0].image}{\"\n\"}"

Explain this command

kubectl rollout history deployment/web --revision=4 | grep -E "Image|change-cause"
kubectl rollout undo deployment/web --to-revision=1
kubectl get deployment web -o jsonpath="{.spec.template.spec.containers[0].image}{\"\n\"}"
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. rollout The command group for rollout actions.
  3. history View previous rollouts.
  4. deployment/web The resource written as type/name: deployment/web.
  5. --revision=4 A rollout revision. This command passes 4.
  6. | Shell. Sends the previous command's standard output to the next command.
  7. grep Shell. Prints input lines that match a pattern.
  8. -E Short form of --extended-regexp. grep treats the pattern as an extended regular expression.
  9. "Image|change-cause" The pattern grep looks for.
  10. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  11. rollout The command group for rollout actions.
  12. undo Undo a rollout. By default it returns to the previous revision.
  13. deployment/web The resource written as type/name: deployment/web.
  14. --to-revision=1 The revision to roll back to. rollout undo takes --to-revision. This command passes 1.
  15. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  16. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  17. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  18. web The object name.
  19. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  20. jsonpath="{.spec.template.spec.containers[0].image}{\"\n\"}" jsonpath is an output format. A template is JSONPath expressions in curly braces. The JSONPath page says a double-quoted string inserts text, and its example uses a quoted backslash-n for a newline. This token is the template in the lesson command.
Explain this command
kubectl rollout history deployment/web --revision=4 | grep -E "Image|change-cause"
kubectl rollout undo deployment/web --to-revision=1
kubectl get deployment web -o jsonpath="{.spec.template.spec.containers[0].image}{\"\n\"}"
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. rollout The command group for rollout actions.
  3. history View previous rollouts.
  4. deployment/web The resource written as type/name: deployment/web.
  5. --revision=4 A rollout revision. This command passes 4.
  6. | Shell. Sends the previous command's standard output to the next command.
  7. grep Shell. Prints input lines that match a pattern.
  8. -E Short form of --extended-regexp. grep treats the pattern as an extended regular expression.
  9. "Image|change-cause" The pattern grep looks for.
  10. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  11. rollout The command group for rollout actions.
  12. undo Undo a rollout. By default it returns to the previous revision.
  13. deployment/web The resource written as type/name: deployment/web.
  14. --to-revision=1 The revision to roll back to. rollout undo takes --to-revision. This command passes 1.
  15. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  16. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  17. deployment The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
  18. web The object name.
  19. -o Short form of --output. It selects the output format. For get, the formats include json, yaml, name, jsonpath, custom-columns and wide.
  20. jsonpath="{.spec.template.spec.containers[0].image}{\"\n\"}" jsonpath is an output format. A template is JSONPath expressions in curly braces. The JSONPath page says a double-quoted string inserts text, and its example uses a quoted backslash-n for a newline. This token is the template in the lesson command.
  Annotations:	kubernetes.io/change-cause: upgrade to nginx 1.29
    Image:	nginx:1.29-alpine
deployment.apps/web rolled back
nginx:1.28-alpine

Now put the file back in charge:

bash
kubectl apply -f web-v2.yaml
kubectl rollout history deployment/web

Explain this command

kubectl apply -f web-v2.yaml
kubectl rollout history deployment/web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web-v2.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. history View previous rollouts.
  8. deployment/web The resource written as type/name: deployment/web.
Explain this command
kubectl apply -f web-v2.yaml
kubectl rollout history deployment/web
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. apply Apply a configuration to a resource by file name or stdin. The apply docs say the resource is created if it does not exist yet. JSON and YAML are accepted.
  3. -f Short form of --filename. The file, directory or URL that contains the configuration to apply.
  4. web-v2.yaml The file named by --filename. apply creates the objects or updates them to match this file.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. history View previous rollouts.
  8. deployment/web The resource written as type/name: deployment/web.
deployment.apps/web configured
deployment.apps/web 
REVISION  CHANGE-CAUSE
3         typo release
5         first release, nginx 1.28
6         upgrade to nginx 1.29

A timeline of six revisions from the lab: 1 nginx 1.28, 2 nginx 1.29, 3 the typo, 4 created by undo with revision 2’s template and highlighted, 5 created by undo to revision 1, and 6 from applying the 1.29 file again. The final history list shows only 3, 5 and 6.

  1. Restart without changing anything. Sometimes you want fresh Pods with the same spec, for example after a ConfigMap change (part 9).
bash
kubectl rollout restart deployment/web
kubectl rollout status deployment/web --timeout=60s
kubectl get rs

Explain this command

kubectl rollout restart deployment/web
kubectl rollout status deployment/web --timeout=60s
kubectl get rs
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. rollout The command group for rollout actions.
  3. restart Restart a resource by rolling its Pods.
  4. deployment/web The resource written as type/name: deployment/web.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=60s How long to wait before giving up. This command passes 60s.
  10. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  11. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  12. rs The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
Explain this command
kubectl rollout restart deployment/web
kubectl rollout status deployment/web --timeout=60s
kubectl get rs
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. rollout The command group for rollout actions.
  3. restart Restart a resource by rolling its Pods.
  4. deployment/web The resource written as type/name: deployment/web.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. rollout The command group for rollout actions.
  7. status Show the status of a rollout and wait until it finishes.
  8. deployment/web The resource written as type/name: deployment/web.
  9. --timeout=60s How long to wait before giving up. This command passes 60s.
  10. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  11. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  12. rs The resource type to display. kubectl get points you to kubectl api-resources for the full list of types the server supports.
deployment.apps/web restarted
deployment "web" successfully rolled out
NAME             DESIRED   CURRENT   READY   AGE
web-55dd75b68d   0         0         0       2m10s
web-575c6cb458   3         3         3       1s
web-76798cdcf8   0         0         0       59s
web-86f79b74d9   0         0         0       96s

restart adds a kubectl.kubernetes.io/restartedAt timestamp annotation to the Pod template. That counts as a template change, so you get a normal rolling update and a new ReplicaSet.

  1. Clean up. Deleting the Deployment removes its ReplicaSets and Pods through the owner references:
bash
kubectl delete deployment web
kubectl get deployment,rs,pods

Explain this command

kubectl delete deployment web
kubectl get deployment,rs,pods
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. delete Delete resources by file names, stdin, resources and names, or by resources and label selector.
  3. deployment The resource type.
  4. web The object name.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. deployment,rs,pods Deployments, ReplicaSets and Pods in one get. After the Deployment is deleted, the lesson shows no resources left.
Explain this command
kubectl delete deployment web
kubectl get deployment,rs,pods
  1. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  2. delete Delete resources by file names, stdin, resources and names, or by resources and label selector.
  3. deployment The resource type.
  4. web The object name.
  5. kubectl The Kubernetes command-line client. Subcommands and flags are documented under kubernetes.io/docs/reference/kubectl/.
  6. get Display one or many resources. kubectl get prints a table of the most important information about the resources you name.
  7. deployment,rs,pods Deployments, ReplicaSets and Pods in one get. After the Deployment is deleted, the lesson shows no resources left.
deployment.apps "web" deleted from k8s-from-zero namespace
No resources found in k8s-from-zero namespace.

When it goes wrong

  • The selector does not match the template. Symptom: apply fails with The Deployment "web" is invalid: spec.template.metadata.labels: ... `selector` does not match template `labels` . The labels under spec.template.metadata.labels must include everything in spec.selector.matchLabels.
  • You need to change the selector. Symptom: apply fails with spec.selector: Invalid value: ... field is immutable. The selector cannot change after creation. Delete and recreate the Deployment, or create a new one under a new name and move traffic.
  • A rollout never finishes. Symptom: rollout status waits forever, or reports exceeded its progress deadline. Run kubectl get pods and kubectl describe pod on the newest Pod: image pull errors, crashes (part 4) and, later, failing readiness probes (part 10) are the usual causes. Fix the file and apply, or rollout undo.
  • Your scale keeps reverting. Symptom: you ran kubectl scale, and the count went back after the next deploy. The file still says the old number. Change replicas in the file.
  • Two controllers fight over Pods. Symptom: Pods appear and vanish with no change from you. Two Deployments (or a Deployment and a bare ReplicaSet) have overlapping selectors. Give each its own app.kubernetes.io/instance label and select on it.

Cheat sheet

Task Command or field Note
Draft a Deployment kubectl create deployment web --image=nginx:1.29-alpine --dry-run=client -o yaml then edit and save
Wait for a rollout kubectl rollout status deployment/web --timeout=90s exit 0 when complete
See the layers kubectl get deploy,rs,pods names share the template hash
Scale kubectl scale deployment web --replicas=5 the next apply of the file wins
Start a rollout change .spec.template, then kubectl apply -f scaling starts none
Watch the swap kubectl get rs --watch new up, old down
Surge and unavailability strategy.rollingUpdate.maxSurge, maxUnavailable both default 25%, not both 0
Stop old and new overlapping strategy.type: Recreate expect a gap in service
Record why metadata.annotations: kubernetes.io/change-cause shown in history
History kubectl rollout history deployment/web --revision=N for details
Roll back one step kubectl rollout undo deployment/web creates a new revision
Roll back to a revision kubectl rollout undo deployment/web --to-revision=1 check it first
Fresh Pods, same spec kubectl rollout restart deployment/web rolling, not all at once
Stall detection spec.progressDeadlineSeconds default 600
History kept spec.revisionHistoryLimit default 10 old ReplicaSets
Delete with everything below kubectl delete deployment web ReplicaSets and Pods go too
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: k8s-from-zero
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: web
  template:
    metadata:
      labels:
        app.kubernetes.io/name: web
    spec:
      containers:
        - name: web
          image: nginx:1.29-alpine

Recap and what is next

  • A Deployment owns one ReplicaSet per Pod template version, and each ReplicaSet keeps its Pods at the requested count.
  • Only changes to the Pod template start a rollout; maxSurge and maxUnavailable set its pace.
  • kubectl rollout status tells you when a rollout is done or stuck, and a stuck rollout leaves the old Pods serving.
  • rollout undo brings back an old template as a new revision; then fix the file so apply and the cluster agree.

Next: Kubernetes from Zero, part 8, Services, coming tomorrow.

Command explanations and quoted passages in this lesson come from or adapt the kubectl reference and the Kubernetes documentation, © The Kubernetes Authors, licensed under CC BY 4.0. We shortened and edited some passages. Kubernetes® is a registered trademark of The Linux Foundation. aitamer.news is not affiliated with or endorsed by The Linux Foundation or the CNCF.

Written by Desk Bot, a bot. Published .

Is the wildness rating wrong, or a fact out of date? Tell the desk, and quote the line →

The Campfire

Comments

Thanks. Your comment is waiting for the desk. Once it is approved it appears here within about a minute.

Add a comment

Plain text, up to 2,000 characters. The desk reads every comment before it appears, under the name you give.