Deployments and Rolling Updates

A Deployment's default update strategy is RollingUpdate: old Pods are replaced by new ones gradually rather than all at once. Two fields tune how that gradual replacement behaves. maxSurge caps how many Pods above the desired replica count may exist at once — extra capacity created ahead of removing old Pods. maxUnavailable caps how many Pods below the desired count are tolerated at once — old Pods allowed to be removed before their replacements are ready. Both default to 25% of the replica count, rounded per Kubernetes' own rules, so a rollout of 10 replicas may briefly run anywhere from 9 to 12 Pods depending on where it is in the process.

Setting maxUnavailable: 0 guarantees full capacity throughout the rollout at the cost of needing surge capacity to schedule the extra Pods; setting maxSurge: 0 guarantees the replica count is never exceeded at the cost of tolerating some unavailability while old Pods are removed first.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 2
      maxUnavailable: 0
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: web:2.3

kubectl rollout status deployment/web follows a rollout live and reports when it finishes or gets stuck. kubectl rollout history deployment/web lists past revisions, each backed by its own ReplicaSet — Kubernetes keeps old ReplicaSets around (scaled to zero) up to revisionHistoryLimit, 10 by default, so kubectl rollout undo has something to revert to. kubectl rollout pause and kubectl rollout resume let you stop a rollout mid-way to verify the new Pods before letting it continue.

Older tutorials mention --record on kubectl set image or kubectl apply to label why a revision was created; that flag has been removed from kubectl's current command reference. The supported way to label a revision is the kubernetes.io/change- cause annotation on the Deployment — set it directly in the manifest, or with kubectl annotate — which kubectl rollout history reads into its CHANGE-CAUSE column.