2.3. Pods

In this lab, you follow a Pod through its lifecycle, run several containers in one Pod, organize Pods with labels and separate them with namespaces.

Step 1: Follow the Lifecycle of a Pod

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

mkdir -p ~/labs/2.3
cd ~/labs/2.3

Create the file countdown.yaml in ~/labs/2.3. The Pod counts down from 5 and then ends:

apiVersion: v1
kind: Pod
metadata:
  name: countdown
spec:
  restartPolicy: Never
  containers:
    - name: countdown
      image: busybox:1.37
      command: ["sh", "-c", "for i in 5 4 3 2 1; do echo $i; sleep 2; done"]

Create the Pod:

kubectl apply -f countdown.yaml
pod/countdown created

Watch the Pod right away. --watch keeps the command running and prints a new line for every change:

kubectl get pod countdown --watch
NAME        READY   STATUS              RESTARTS   AGE
countdown   0/1     ContainerCreating   0          0s
countdown   1/1     Running             0          4s
countdown   0/1     Completed           0          16s

Once the status is Completed (after about 15 seconds), stop the watch with Ctrl+C and show what the container printed:

kubectl logs countdown
5
4
3
2
1

Explanation

Every Pod goes through phases. The column STATUS shows them in more detail:

PhaseStatusMeaning
PendingContainerCreatingThe Pod has a node, which downloads the image and starts the container
RunningRunningThe container runs
SucceededCompletedThe container ended successfully

command replaces the default command of the image. restartPolicy: Never tells Kubernetes not to start the container again after it ended.


Step 2: Restart the Container Automatically

Change the restartPolicy in countdown.yaml from Never to Always:

spec:
  restartPolicy: Always

The restartPolicy of an existing Pod can’t be changed. Delete the Pod:

kubectl delete -f countdown.yaml
pod "countdown" deleted from default namespace

Create it again:

kubectl apply -f countdown.yaml
pod/countdown created

Watch it for about a minute:

kubectl get pod countdown --watch
NAME        READY   STATUS              RESTARTS      AGE
countdown   0/1     ContainerCreating   0             0s
countdown   1/1     Running             0             1s
countdown   0/1     Completed           0             11s
countdown   1/1     Running             1 (2s ago)    12s
countdown   0/1     Completed           1 (12s ago)   22s
countdown   0/1     CrashLoopBackOff    1 (11s ago)   32s
countdown   1/1     Running             2 (12s ago)   33s
countdown   0/1     Completed           2 (22s ago)   43s

Stop the watch with Ctrl+C.

Explanation

With restartPolicy: Always, Kubernetes starts the container again every time it ends, even after a successful run. RESTARTS counts how often that happened. Despite its name, CrashLoopBackOff doesn’t mean that the container crashed: the container keeps ending, so Kubernetes waits a little longer before every new restart, up to 5 minutes.

Always is the default and the right policy for servers like nginx, which should run all the time. Never fits tasks that end. The countdown keeps restarting for the rest of this lab.


Step 3: Run Several Containers in One Pod

Create the file web.yaml in ~/labs/2.3 with a Pod that runs three containers:

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  initContainers:
    - name: wait
      image: busybox:1.37
      command: ["sh", "-c", "echo Waiting for the database...; sleep 10"]
  containers:
    - name: nginx
      image: nginx:1.29
    - name: checker
      image: busybox:1.37
      command: ["sh", "-c", "trap 'exit 0' TERM; while true; do wget -q -O /dev/null http://localhost && echo nginx is up; sleep 5; done"]

Create the Pod:

kubectl apply -f web.yaml
pod/web created

Watch it right away:

kubectl get pod web --watch
NAME   READY   STATUS            RESTARTS   AGE
web    0/2     Init:0/1          0          0s
web    0/2     PodInitializing   0          11s
web    2/2     Running           0          18s

The init container needs about 10 seconds, so Init:0/1 stays for a while. Once READY shows 2/2 (after about 20 seconds), stop the watch with Ctrl+C. Show the output of the container checker:

kubectl logs web -c checker
nginx is up
nginx is up
...

Explanation

The Pod starts its containers in two stages:

  1. The init container wait runs first and has to end successfully. Here it only sleeps for 10 seconds; in a real app, it would wait until the database is reachable. Meanwhile, the status is Init:0/1: 0 of 1 init containers have finished.
  2. Then the containers nginx and checker start together. While they are being created, the status is PodInitializing. READY 2/2 means both of them run.

All containers of a Pod share the same network. That’s why checker reaches nginx at localhost. A helper container like checker that runs next to the main container is called a sidecar.

trap 'exit 0' TERM lets checker end within a few seconds when Kubernetes stops the Pod. Without it, deleting the Pod takes 30 seconds: Kubernetes waits that long for a container to end before it kills it.

Without -c, kubectl logs shows the first container, nginx. Use -c to choose another one.


Step 4: Organize Pods with Labels

Add labels to the metadata of both manifests. In countdown.yaml:

metadata:
  name: countdown
  labels:
    app: countdown
    env: dev

In web.yaml:

metadata:
  name: web
  labels:
    app: web
    env: dev

Apply all manifests in the directory at once:

kubectl apply -f .
pod/countdown configured
pod/web configured

Show the labels of the Pods:

kubectl get pods --show-labels
NAME        READY   STATUS             RESTARTS      AGE   LABELS
countdown   0/1     CrashLoopBackOff   3 (13s ago)   90s   app=countdown,env=dev
web         2/2     Running            0             30s   app=web,env=dev

countdown keeps restarting, so its status may also be Running or Completed. Your RESTARTS and AGE differ.

Select the Pods with the label app=web:

kubectl get pods -l app=web
NAME   READY   STATUS    RESTARTS   AGE
web    2/2     Running   0          30s

Select the Pods with the label env=dev:

kubectl get pods -l env=dev
NAME        READY   STATUS             RESTARTS      AGE
countdown   0/1     CrashLoopBackOff   3 (13s ago)   90s
web         2/2     Running            0             30s

Explanation

Labels are key-value pairs in the metadata. You choose the keys and values yourself. configured means that Kubernetes updated the existing Pods. Labels can be changed while a Pod runs.

-l takes a selector and returns all Pods with matching labels, regardless of their names. Kubernetes uses selectors in the same way to find the Pods that belong together.


Step 5: Separate Pods with Namespaces

Create a namespace:

kubectl create namespace playground
namespace/playground created

Create a second Pod web in it:

kubectl apply -f web.yaml -n playground
pod/web created

List the Pods in the new namespace:

kubectl get pods -n playground
NAME   READY   STATUS     RESTARTS   AGE
web    0/2     Init:0/1   0          0s

And in the namespace default:

kubectl get pods
NAME        READY   STATUS             RESTARTS      AGE
countdown   0/1     CrashLoopBackOff   3 (13s ago)   90s
web         2/2     Running            0             30s

Delete the namespace. This takes about 10 seconds:

kubectl delete namespace playground
namespace "playground" deleted

Check that its Pod is gone:

kubectl get pods -n playground
No resources found in playground namespace.

Explanation

A Namespace divides a cluster into separate areas. Names only have to be unique within a namespace, so both Pods can be called web. Without -n, kubectl works in the namespace default.

Deleting a namespace deletes everything in it.


Optional Tasks

Finished early? Try these tasks. The following labs don’t depend on them. Task 3 lists the new commands it needs. Open the solution if you get stuck.

Task 1: Second Chance

Set restartPolicy: OnFailure in countdown.yaml. Does the countdown restart now? What changes when its command ends with exit 1?

You know all the commands you need. Remember to delete the Pod before you apply the changed file.

Solution

Change the restartPolicy to OnFailure, then delete the Pod:

kubectl delete -f ~/labs/2.3/countdown.yaml
pod "countdown" deleted from default namespace

Create it again:

kubectl apply -f ~/labs/2.3/countdown.yaml
pod/countdown created

Watch it:

kubectl get pod countdown --watch
NAME        READY   STATUS              RESTARTS   AGE
countdown   0/1     ContainerCreating   0          0s
countdown   1/1     Running             0          1s
countdown   0/1     Completed           0          11s

The countdown isn’t restarted. Now make its command fail with exit 1 at the end:

      command: ["sh", "-c", "for i in 5 4 3 2 1; do echo $i; sleep 2; done; exit 1"]

Delete the Pod again:

kubectl delete -f ~/labs/2.3/countdown.yaml
pod "countdown" deleted from default namespace

Create it again:

kubectl apply -f ~/labs/2.3/countdown.yaml
pod/countdown created

Watch it:

kubectl get pod countdown --watch
NAME        READY   STATUS              RESTARTS      AGE
countdown   0/1     ContainerCreating   0             0s
countdown   1/1     Running             0             1s
countdown   0/1     Error               0             11s
countdown   1/1     Running             1 (1s ago)    12s
countdown   0/1     Error               1 (11s ago)   22s
countdown   0/1     CrashLoopBackOff    1 (13s ago)   34s
...

OnFailure restarts a container only when it fails, i.e. when it ends with an exit code other than 0. It’s the right policy for tasks that should be retried until they succeed.

Task 2: Stuck at the Gate

Create a Pod gate with an init container that fails. Does the main container start? A container fails when its command ends with an exit code other than 0, e.g. exit 1.

Solution

Create the file gate.yaml in ~/labs/2.3:

apiVersion: v1
kind: Pod
metadata:
  name: gate
spec:
  initContainers:
    - name: check
      image: busybox:1.37
      command: ["sh", "-c", "echo Database not reachable; exit 1"]
  containers:
    - name: nginx
      image: nginx:1.29

Create the Pod:

kubectl apply -f ~/labs/2.3/gate.yaml
pod/gate created

Watch it:

kubectl get pod gate --watch
NAME   READY   STATUS                  RESTARTS      AGE
gate   0/1     Init:0/1                0             0s
gate   0/1     Init:Error              0             5s
gate   0/1     Init:CrashLoopBackOff   1 (2s ago)    7s
gate   0/1     Init:Error              2 (15s ago)   20s
...

The container nginx never starts: a Pod only starts its containers after all init containers ended successfully. Kubernetes keeps retrying the init container because of the default restartPolicy: Always. With Never, the Pod would fail instead. The output of the init container shows why it fails:

kubectl logs gate -c check
Database not reachable

Task 3: Label Maker

Show the labels app and env as columns. Add the label tier=frontend to the Pod web, select the Pod by this label and remove the label again.

CommandEffect
kubectl get pods -L <key>,<key>Shows the labels as columns
kubectl label pod <name> <key>=<value>Adds a label to a Pod
kubectl label pod <name> <key>-Removes a label from a Pod
Solution

Show the labels as columns:

kubectl get pods -L app,env
NAME        READY   STATUS             RESTARTS        AGE     APP         ENV
countdown   0/1     CrashLoopBackOff   6 (3m41s ago)   10m     countdown   dev
web         2/2     Running            0               8m47s   web         dev

Add the label:

kubectl label pod web tier=frontend
pod/web labeled

Select the Pod by the new label:

kubectl get pods -l tier=frontend
NAME   READY   STATUS    RESTARTS   AGE
web    2/2     Running   0          8m47s

Remove the label again:

kubectl label pod web tier-
pod/web unlabeled

kubectl label changes the Pod directly, not your manifest. The next kubectl apply -f web.yaml doesn’t remove a label that you added this way.


Clean Up

Delete all Pods of this lab, since the following labs don’t need them:

kubectl delete -f ~/labs/2.3/
pod "countdown" deleted from default namespace
pod "web" deleted from default namespace

If you did Task 2, the Pod gate is deleted as well.


Complete files

~/labs/2.3/countdown.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: countdown
  labels:
    app: countdown
    env: dev
spec:
  restartPolicy: Always
  containers:
    - name: countdown
      image: busybox:1.37
      command: ["sh", "-c", "for i in 5 4 3 2 1; do echo $i; sleep 2; done"]

~/labs/2.3/web.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
    env: dev
spec:
  initContainers:
    - name: wait
      image: busybox:1.37
      command: ["sh", "-c", "echo Waiting for the database...; sleep 10"]
  containers:
    - name: nginx
      image: nginx:1.29
    - name: checker
      image: busybox:1.37
      command: ["sh", "-c", "trap 'exit 0' TERM; while true; do wget -q -O /dev/null http://localhost && echo nginx is up; sleep 5; done"]