2.4. Deployments

In this lab, you run an application as a Deployment, scale it, roll out a new version, roll it back and change it directly in the cluster.

Step 1: Create a Deployment

Create a directory for the files of this lab and change into it:

mkdir -p ~/labs/2.4
cd ~/labs/2.4

Create the file web.yaml in ~/labs/2.4 with a Deployment that runs three nginx Pods:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.28

Create the Deployment:

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

List the Deployment, its ReplicaSet and its Pods:

kubectl get deployments
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    3/3     3            3           13s

If READY isn’t 3/3 yet, the image is still downloading. Wait a moment and repeat the command.

kubectl get replicasets
NAME             DESIRED   CURRENT   READY   AGE
web-77657b99d8   3         3         3       13s
kubectl get pods
NAME                   READY   STATUS    RESTARTS   AGE
web-77657b99d8-4p6q2   1/1     Running   0          14s
web-77657b99d8-kc98z   1/1     Running   0          14s
web-77657b99d8-sr822   1/1     Running   0          14s

Explanation

You don’t create the Pods yourself anymore. The Deployment creates a ReplicaSet, and the ReplicaSet creates and names the Pods: Deployment name, a hash of the Pod template and a random suffix. That’s why the template has no name.

FieldMeaning
replicasNumber of Pods that should run
selectorLabels the Deployment uses to find its Pods (the same as in the template)
templateManifest for the Pods: the same metadata and spec you wrote in 2.3 for a Pod

Step 2: Replace a Deleted Pod

Delete one of the Pods. Use a name from your output:

kubectl delete pod web-77657b99d8-4p6q2

List the Pods again:

kubectl get pods
NAME                   READY   STATUS    RESTARTS   AGE
web-77657b99d8-5mwq8   1/1     Running   0          9s
web-77657b99d8-kc98z   1/1     Running   0          23s
web-77657b99d8-sr822   1/1     Running   0          23s

If the new Pod isn’t Running yet, wait a moment and repeat the command.

Explanation

The ReplicaSet makes sure that three Pods run at all times. It noticed the missing Pod and created a new one. You can recognize it by its new name and its lower age.


Step 3: Scale the Deployment

Change the number of replicas in web.yaml from 3 to 5:

spec:
  replicas: 5

Apply the manifest and list the Pods:

kubectl apply -f web.yaml
deployment.apps/web configured
kubectl get pods
NAME                   READY   STATUS    RESTARTS   AGE
web-77657b99d8-5mwq8   1/1     Running   0          12s
web-77657b99d8-b9f6z   1/1     Running   0          3s
web-77657b99d8-kc98z   1/1     Running   0          26s
web-77657b99d8-sr822   1/1     Running   0          26s
web-77657b99d8-zdckf   1/1     Running   0          3s

If the new Pods aren’t Running yet, wait a moment and repeat the command.

Explanation

The ReplicaSet started two more Pods to reach the new number of replicas. Scaling down works the same way: with a lower number, it deletes Pods.


Step 4: Roll Out a New Version

Change the image in web.yaml to the newer version nginx:1.29:

        - name: nginx
          image: nginx:1.29

Apply the manifest:

kubectl apply -f web.yaml
deployment.apps/web configured

Follow the rollout right away. It takes about 5 seconds:

kubectl rollout status deployment web
Waiting for deployment "web" rollout to finish: 3 out of 5 new replicas have been updated...
...
Waiting for deployment "web" rollout to finish: 1 old replicas are pending termination...
deployment "web" successfully rolled out

If the rollout has already finished, you only see the last line.

List the ReplicaSets:

kubectl get replicasets
NAME             DESIRED   CURRENT   READY   AGE
web-77657b99d8   0         0         0       45s
web-f9b8bfb4c    5         5         5       19s

Explanation

A new image means a new Pod template, so the Deployment creates a second ReplicaSet. During the rolling update, it starts new Pods and stops old ones step by step. Some Pods run at any time, so the application stays available.

The old ReplicaSet stays with 0 replicas. The Deployment needs it to roll back.


Step 5: Roll Back

Show the revisions of the Deployment:

kubectl rollout history deployment web
deployment.apps/web
REVISION  CHANGE-CAUSE
1         <none>
2         <none>

Go back to the previous revision and check the image:

kubectl rollout undo 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
kubectl get deployment web -o wide
NAME   READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES       SELECTOR
web    5/5     5            5           47s   nginx        nginx:1.28   app=web

If UP-TO-DATE isn’t 5 yet, wait a moment and repeat the command.

The warning tells you that web.yaml doesn’t match the cluster anymore: it still says nginx:1.29. Set the image in the file back to nginx:1.28 and apply it:

kubectl apply -f web.yaml
deployment.apps/web configured

Explanation

Each revision is one Pod template and thus one ReplicaSet: revision 1 runs nginx:1.28, revision 2 nginx:1.29. Scaling in Step 3 didn’t create a revision, because it doesn’t change the template. CHANGE-CAUSE stays empty. You can ignore it.

kubectl rollout undo scales the old ReplicaSet up again and the new one down, in a rolling update like before. -o wide adds the column IMAGES, which shows that the old version runs again.

rollout undo is a quick way back in an emergency, but it changes only the cluster, not your manifest. Without the fix in the file, the next kubectl apply would roll out nginx:1.29 again. The apply after the fix changed no Pods: they already run nginx:1.28. It reports configured and not unchanged, because it updated the copy of your last applied manifest that the warning mentioned.


Step 6: Change the Deployment in the Cluster

kubectl edit opens a resource from the cluster in an editor. Choose nano as the editor and open the Deployment:

export KUBE_EDITOR=nano
kubectl edit deployment web

The editor shows the Deployment as Kubernetes stores it, with all default values. Near the top, in the section spec, change replicas: 5 to replicas: 2. Leave the section status at the end as it is: Kubernetes fills it in itself. Save with Ctrl+O and Enter, then close the editor with Ctrl+X:

deployment.apps/web edited

If kubectl reports Edit cancelled, no changes made., you closed the editor without saving. Repeat the command.

List the Deployment:

kubectl get deployment web
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    2/2     2            2           65s

If READY isn’t 2/2 yet, wait a moment and repeat the command.

web.yaml still says replicas: 5. Apply it and list the Deployment again:

kubectl apply -f web.yaml
deployment.apps/web configured
kubectl get deployment web
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    5/5     5            5           70s

If READY isn’t 5/5 yet, wait a moment and repeat the command.

Explanation

kubectl edit is imperative, like kubectl run in 2.2 and kubectl rollout undo in Step 5: you change the Deployment directly in the cluster, and no file records the change. Your manifest still said replicas: 5, so the next kubectl apply scaled the Deployment back up. Without KUBE_EDITOR, kubectl edit uses the editor in EDITOR, or else vi. The export lasts until you close the terminal.

Use kubectl edit only for a quick fix in an emergency or to try something out, and write every change you want to keep into the manifest. The manifest stays the source of truth: you can review it, keep it in Git and apply it again at any time.


Optional Tasks

Finished early? Try these tasks. The following labs don’t depend on them. Each task lists the commands you need. Open the solution if you get stuck.

Task 1: Bad Release

Roll out a version that doesn’t exist, e.g. nginx:1.299. What happens to the running Pods? Then repair the Deployment.

You know all the commands you need.

Solution

Change the image in web.yaml to nginx:1.299 and apply the manifest:

kubectl apply -f ~/labs/2.4/web.yaml
deployment.apps/web configured

After a few seconds, list the Pods:

kubectl get pods
NAME                   READY   STATUS             RESTARTS   AGE
web-77657b99d8-dfjv4   1/1     Running            0          27s
web-77657b99d8-dplnh   1/1     Running            0          26s
web-77657b99d8-j6lr7   1/1     Running            0          27s
web-77657b99d8-ppj8b   1/1     Running            0          27s
web-7fb8cfd776-q4xl4   0/1     ErrImagePull       0          25s
web-7fb8cfd776-t4sln   0/1     ImagePullBackOff   0          25s
web-7fb8cfd776-v6zn9   0/1     ImagePullBackOff   0          25s

The new Pods can’t download the image, so the rollout gets stuck. By default, a rolling update may take a quarter of the replicas out of service (maxUnavailable) and start a quarter extra (maxSurge). With 5 replicas, that’s 1 Pod less and 2 Pods more. So the Deployment stopped one old Pod right away and started three new ones, but it stops no more old Pods until new ones are ready: the application stays available.

Set the image back to nginx:1.28 and apply the manifest again. The Deployment removes the broken Pods:

kubectl apply -f ~/labs/2.4/web.yaml
deployment.apps/web configured
kubectl rollout status deployment web
...
deployment "web" successfully rolled out

Task 2: Drain the Node

Take an agent node out of service for maintenance and watch where its Pods go. Then put the node back into service.

CommandEffect
kubectl get pods -o wideAlso shows the node of each Pod in the column NODE
kubectl drain <node> --ignore-daemonsets --delete-emptydir-dataMoves all Pods away from a node and blocks new ones
kubectl uncordon <node>Allows new Pods on the node again
Solution

Check where the Pods run:

kubectl get pods -o wide
NAME                   READY   STATUS    RESTARTS   AGE   IP           NODE                NOMINATED NODE   READINESS GATES
web-77657b99d8-2hdpp   1/1     Running   0          3s    10.42.2.10   k3d-labs-agent-1    <none>           <none>
web-77657b99d8-48q9h   1/1     Running   0          3s    10.42.1.10   k3d-labs-server-0   <none>           <none>
web-77657b99d8-6lv72   1/1     Running   0          3s    10.42.0.9    k3d-labs-agent-0    <none>           <none>
web-77657b99d8-jjsxb   1/1     Running   0          2s    10.42.1.11   k3d-labs-server-0   <none>           <none>
web-77657b99d8-s6cqg   1/1     Running   0          2s    10.42.2.11   k3d-labs-agent-1    <none>           <none>

Drain the node k3d-labs-agent-1:

kubectl drain k3d-labs-agent-1 --ignore-daemonsets --delete-emptydir-data
node/k3d-labs-agent-1 cordoned
evicting pod default/web-77657b99d8-2hdpp
evicting pod default/web-77657b99d8-s6cqg
pod/web-77657b99d8-2hdpp evicted
pod/web-77657b99d8-s6cqg evicted
node/k3d-labs-agent-1 drained

If add-on Pods from kube-system run on the node, the drain evicts them as well. Without the two flags, it stops at certain Pods: --ignore-daemonsets skips Pods that must run on every node, so they stay where they are. --delete-emptydir-data evicts Pods that keep temporary data on the node, like the metrics-server.

Check the Pods again. The ReplicaSet replaced the two evicted Pods on the other nodes:

kubectl get pods -o wide
NAME                   READY   STATUS    RESTARTS   AGE   IP           NODE                NOMINATED NODE   READINESS GATES
web-77657b99d8-48q9h   1/1     Running   0          10s   10.42.1.10   k3d-labs-server-0   <none>           <none>
web-77657b99d8-6lv72   1/1     Running   0          10s   10.42.0.9    k3d-labs-agent-0    <none>           <none>
web-77657b99d8-7bchc   1/1     Running   0          7s    10.42.0.10   k3d-labs-agent-0    <none>           <none>
web-77657b99d8-d5b7t   1/1     Running   0          7s    10.42.1.12   k3d-labs-server-0   <none>           <none>
web-77657b99d8-jjsxb   1/1     Running   0          9s    10.42.1.11   k3d-labs-server-0   <none>           <none>

If the new Pods aren’t Running yet, wait a moment and repeat the command.

kubectl get nodes shows the drained node as Ready,SchedulingDisabled. Put it back into service:

kubectl uncordon k3d-labs-agent-1
node/k3d-labs-agent-1 uncordoned

The Pods don’t move back by themselves. Only new Pods can be placed on the node again.


Clean Up

Delete the Deployment, since the following labs don’t need it:

kubectl delete -f ~/labs/2.4/
deployment.apps "web" deleted from default namespace

Kubernetes deletes the ReplicaSets and Pods of the Deployment along with it.

If you did Task 2, check with kubectl get nodes that no node shows SchedulingDisabled. If one does, run kubectl uncordon <node>.


Complete files

~/labs/2.4/web.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 5
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.28