Home / Deployment template

Kubernetes Deployment YAML template explained

Reference guide · every field, what it does, and what happens if you leave it at its default.

A Deployment is the resource the vast majority of stateless applications on Kubernetes use: you tell it how many replicas of your Pod you want and which image to run, and the controller keeps that number running, replacing Pods that fail and rolling out updates in a controlled way. Here is a minimal but complete example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: nginx:1.25
          ports:
            - containerPort: 80
              protocol: TCP
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 250m
              memory: 256Mi

Field by field

apiVersion: apps/v1 — the stable API version where Deployment has lived since Kubernetes 1.9. There is no reason to use anything else on a modern cluster.

spec.replicas — how many identical Pods you want running at once. If you later add a HorizontalPodAutoscaler pointing at this Deployment, this number becomes a starting point that the HPA can change automatically.

spec.selector.matchLabels — the criterion the Deployment uses to know which Pods are "its own". It must match exactly the labels defined in spec.template.metadata.labels. It is an immutable field: if you change it after creating the Deployment, Kubernetes rejects the update.

spec.strategy — how old Pods are replaced by new ones when you update the image. RollingUpdate (the default) replaces Pods progressively, controlling how many extra there may be (maxSurge) and how many may be missing (maxUnavailable) during the transition. Recreate deletes every old Pod before creating the new ones — useful only when your app can't tolerate two versions running at once.

spec.template — the template of the Pod the Deployment will create. Everything inside it (image, ports, environment variables, resources) is exactly what you would define in a standalone Pod, except here it is replicated automatically.

resources.requests / resources.limits — requests is what the Pod asks for in order to be scheduled onto a node (the scheduler only places the Pod on a node with that much CPU/memory free); limits is the ceiling the kubelet enforces. If the Pod exceeds the memory limit it is restarted (OOMKilled); if it exceeds the CPU limit it is simply throttled, not killed.

Common mistakes when writing a Deployment by hand

• Forgetting that selector and the template labels must match letter for letter — the most common cause of a Deployment that creates Pods while a Service never finds them.
• Mixing tabs and spaces in the YAML — Kubernetes, like any standard YAML parser, rejects tabs in indentation.
• Leaving out resources.limits — without them, a Pod with a memory leak can consume the whole node's memory and take other Pods down with it.

If you would rather not write it by hand, our Kubernetes manifest generator builds this same YAML from a form, with indentation guaranteed and no required fields forgotten.

← Back to the generator