From a Pod to a Deployment

You can write a directly. Here's the smallest useful one:

apiVersion: v1
kind: Pod
metadata:
  name: shop
  labels:
    app: shop          # (1) the name tag
spec:
  containers:
    - name: shop
      image: shop:1.0  # (2) which container image
      ports:
        - containerPort: 8080
1

labels are free-form name tags. You'll use them to find this Pod later.

2

image is the container to run, as name:tag.

But a bare has nobody looking after it. If its ship sinks or you delete it, it's simply gone. Nothing brings it back.

A lone Pod with no Deployment? Delicious. One swipe and he’s gone for good. That is why I never sail alone, Cyclops. A Deployment keeps a clerk counting heads: swipe me away and a fresh Pod takes my place.

So you write a Deployment instead, a standing order that wraps a Pod recipe:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop
spec:
  replicas: 3              # (1) how many copies you want
  selector:
    matchLabels:
      app: shop            # (2) which Pods count as "mine"
  template:                # (3) the recipe for each Pod
    metadata:
      labels:
        app: shop          # (4) must match (2)!
    spec:
      containers:
        - name: shop
          image: shop:1.0
1

replicas: the number you want running at all times.

2

selector: how the Deployment recognises its own Pods: anything wearing app: shop.

3

template: the Pod recipe. It's the Pod from above, minus its name: the Deployment names each copy itself.

4

The template's labels must match the selector. If they don't, Kubernetes refuses the Deployment with `selector` does not match template `labels`.

The chain of command

A Deployment doesn't make Pods itself. It hires a ReplicaSet to keep the count, and the ReplicaSet makes the Pods. You can see the chain in the names:

deployment:  shop
replicaset:  shop-7d9c5b8f4
pods:        shop-7d9c5b8f4-xk2pq
             shop-7d9c5b8f4-m8vtn
             shop-7d9c5b8f4-b4wlz
One thing you can't change later: a Deployment's selector. Edit it on an existing apps/v1 Deployment and the API server answers field is immutable. Keep the selector and change the template labels so they still match it, or delete and recreate the Deployment. Why the middleman? When you change the Deployment, for example a new image, it creates a new ReplicaSet and shifts Pods over gradually. That's a rolling update, and it gets its own chapter (8).