Kubernetes Deployment YAML Generator

Kubernetes Deployments in depth: rolling updates, probes, resources, and best practices

A Deployment is the Kubernetes controller that manages stateless replicated workloads. Under the hood it creates a ReplicaSet (which in turn manages the Pods), and during an update it spins up a new ReplicaSet, gradually shifts replicas from the old to the new, and keeps the old around so you can roll back. The whole thing is declarative: you describe the desired state in YAML, run kubectl apply, and the controller drives the cluster toward it.

Use Deployments for HTTP APIs, workers, batch consumers — anything where any pod can be replaced by any other. For workloads that need stable identity, ordered startup, or per-pod storage, reach for StatefulSet instead.

Minimum manifest skeleton

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels: { app: my-app }
spec:
  replicas: 3
  selector:
    matchLabels: { app: my-app }
  template:
    metadata:
      labels: { app: my-app }
    spec:
      containers:
      - name: app
        image: ghcr.io/me/my-app:1.4.2
        ports: [{ containerPort: 8080 }]
        env:
        - name: NODE_ENV
          value: production
        resources:
          requests: { cpu: 100m, memory: 128Mi }
          limits:   { cpu: 500m, memory: 512Mi }
        readinessProbe:
          httpGet: { path: /healthz, port: 8080 }
          periodSeconds: 5
        livenessProbe:
          httpGet: { path: /healthz, port: 8080 }
          initialDelaySeconds: 15

Note the three places labels appear: metadata.labels (descriptive), spec.selector.matchLabels (which pods this Deployment owns — immutable after creation), and spec.template.metadata.labels (stamped onto each Pod, must match the selector).

Resources: requests, limits, and the QoS class

resources.requests is what the scheduler uses to pick a node — if you ask for 500 MiB, you only land on nodes with 500 MiB free. resources.limits is the hard ceiling enforced by the kernel: CPU above the limit is throttled, memory above the limit triggers an OOM kill. Setting requests but not limits gives the pod the Burstable QoS class; setting both to the same value gives Guaranteed (safer for latency-sensitive workloads). Missing both: BestEffort, evicted first under pressure.

Probes: liveness, readiness, startup

• livenessProbe — "is the process healthy?" Failure restarts the container. Use sparingly; an aggressive liveness probe can amplify a transient hiccup into a crash loop.
• readinessProbe — "should this pod receive traffic?" Failure removes the pod from the Service's endpoint list but does not restart it. Use this during slow startup or temporary backpressure.
• startupProbe — "is the app done initialising?" Disables the other probes until it passes. Essential for legacy apps that take 60+ seconds to boot — without it, the liveness probe would kill them mid-startup.

Update strategy

Default is RollingUpdate with maxSurge: 25% and maxUnavailable: 25%. That means during an update Kubernetes can have up to 125% of replicas alive and at most 25% missing — zero-downtime for any service backed by a load balancer. Set both to 1 for tight resource budgets, or use Recreate (kills all old pods first) for stateful migrations that cannot tolerate two versions at once.

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

Scheduling: affinity, tolerations, topology spread

• nodeAffinity — run only on nodes with specific labels (gpu=true, zone=sa-east-1a).
• podAffinity — co-locate with another pod (e.g., put the cache next to its app).
• podAntiAffinity — spread replicas across zones/hosts; the standard pattern for HA.
• tolerations — let pods land on tainted nodes (dedicated GPU pool, spot fleet, etc.).
• topologySpreadConstraints — modern replacement for anti-affinity, more efficient at scheduling.

Best practices

• Always set resources.requests — without them the scheduler can pack nodes until they OOM.
• Pin image tags (:1.4.2) instead of :latest; otherwise rollouts become unreproducible.
• Set imagePullPolicy: IfNotPresent for tagged images (avoids hammering the registry).
• Add a securityContext with runAsNonRoot: true, readOnlyRootFilesystem: true, and drop all capabilities.
• Use a PodDisruptionBudget to guarantee minimum replicas during node maintenance.
• Inject configuration via envFrom (ConfigMap) and secrets via envFrom (Secret) — never bake them into the image.
• Package with Helm for reusable charts, or Kustomize for per-environment overlays.

FAQ

Can I set replicas and use HPA at the same time? Set the initial value in the manifest, then let the HorizontalPodAutoscaler take over. Re-applying the Deployment will not override the HPA-managed replica count if you remove the replicas field — keep it out of source control once HPA is active.

Can a Deployment have multiple containers (sidecars)? Yes. spec.template.spec.containers is a list. The classic example is a sidecar proxy (Envoy, Istio) or a log shipper that tails a shared emptyDir.

Does Kubernetes automatically roll back a failed deploy? No. It will stop the rollout (if you set progressDeadlineSeconds) and surface the failure, but you have to run kubectl rollout undo deploy/api manually. Argo Rollouts and Flagger add automatic rollback on metric thresholds.

Can a Deployment use a PersistentVolumeClaim? Technically yes, but every replica would mount the same volume — almost always a bug. If you need per-pod storage, switch to a StatefulSet with volumeClaimTemplates.

Why is my new pod stuck in Pending? Usually insufficient cluster resources (kubectl describe pod → "0/N nodes available: ... insufficient cpu/memory"), a node selector that matches no nodes, or a PVC that cannot be provisioned.

How do I trigger a redeploy without changing the image tag? The clean trick is annotating the pod template with a timestamp or git SHA — any change to spec.template creates a new ReplicaSet: kubectl rollout restart deploy/api does exactly this.