Kubernetes / Intermediate: rollout, policy, and evidence / Lesson 7

Deployments and rollout evidence

Read replica transitions and compatibility constraints before interpreting a rollout as safe or complete.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Explain the model, assumptions, and boundaries of deployments and rollout evidence.
Interpret both examples and distinguish declared intent from established evidence.
Diagnose the listed failures and justify the worked recovery decisions without executing cluster operations.

A Deployment owns a changing replica set

A Deployment expresses a Pod template and replica intent and uses ReplicaSets to manage rollout. Changing the template differs from changing an unrelated annotation on the Deployment itself. New and old replicas can coexist, so application protocols, sessions, database schema, and message formats need compatibility. The controller manages instance transitions, not the correctness of accepted business writes. Record the exact template revision, image identity, configuration references, and rollout strategy before comparing status. A mutable image tag can hide different bytes under one label and weakens the evidence needed for diagnosis or recovery.

Interpret surge and unavailable capacity

RollingUpdate uses maxSurge and maxUnavailable to constrain replica transitions. Integer and percentage forms have documented rounding rules; do not assume a percentage always means at least one replica. The first complete illustrative Deployment uses integer values to make its three-replica example clear. maxSurge one can require temporary capacity for an extra Pod, while maxUnavailable zero asks the rollout to preserve the requested availability according to controller rules. It does not guarantee zero user errors, unlimited backend capacity, or survival of unrelated node failures. Pending surge replicas can stall progress when scheduling or storage constraints are unmet.

yaml Illustrative apps/v1 rollout

apiVersion: apps/v1
kind: Deployment
metadata: {name: booking-api, namespace: training}
spec:
  replicas: 3
  selector: {matchLabels: {app: booking}}
  strategy:
    type: RollingUpdate
    rollingUpdate: {maxSurge: 1, maxUnavailable: 0}
  template:
    metadata: {labels: {app: booking}}
    spec:
      containers:
        - name: api
          image: registry.invalid/training/booking:lab42
          ports: [{name: http, containerPort: 8080}]

registry.invalid deliberately cannot designate a production registry. The image reference is fictional, and this object lacks a production probe, resources, security, and immutable digest policy. It is never applied.

Distinguish progress, readiness, and user success

Observed generation, replica counts, conditions, readiness, and available replicas answer different questions. A controller progress deadline can report lack of progress; it does not automatically design the recovery decision or reverse incompatible data. minReadySeconds can require stable readiness before availability accounting, but it is not a substitute for meaningful probes. The second synthetic timeline shows a new replica waiting for capacity while old replicas continue. Read the exact condition and Pod evidence instead of increasing deadlines blindly. A user-path check and post-release observation remain necessary even after controller counts converge.

text Synthetic rollout capacity evidence

desired replicas: 3
old available: 3
new Pod: Pending, insufficient placement capacity
controller: rollout not yet complete
interpretation: inspect feasibility before extending deadlines

Old replicas remain available while the surge Pod cannot fit. This is a capacity hypothesis tied to a stated event, not proof that every stalled rollout has the same cause.

Review rollback against current state

A rollback changes workload intent to a prior template, not every external effect of the release. Check current schema, persisted data, credentials, and messages before choosing that path. An old image may be unavailable or incompatible with a rotated secret. Keep immutable artifacts and a reviewed recovery contract, and prefer forward repair when a safe return is no longer possible. Do not edit generated ReplicaSets or Pods as the normal release workflow. Multiple tools managing the same template can produce a race that looks like spontaneous rollback; identify ownership before making another change.

Set completion and abort conditions

Before exposure, define acceptable availability, user error and latency behavior, data invariants, and an accountable abort decision. Include headroom for surge and dependency connections. Verify all intended replicas use the reviewed identity and that no old consumer still requires a deprecated contract. Reconcile side effects before declaring recovery complete. All manifests and timelines here are illustrative and non-runnable: no image is fetched, rollout started, or workload changed. YAML parsing checks structure only. Actual rollout behavior must be verified against the installed Kubernetes version, policy, and application in an authorized isolated environment.

Common errors and fixes

The rollout stalls despite healthy old replicas

Why it happens: Surge requires unavailable placement or storage capacity.
How to fix it: Inspect scheduling and volume constraints before strategy changes.
Prevent it next time: Budget rollout headroom explicitly.

Rollback reintroduces incompatible readers

Why it happens: Current data compatibility was not checked.
How to fix it: Choose the reviewed forward or reconciliation recovery path.
Prevent it next time: Test mixed-version reads and writes before exposure.

A progress deadline is treated as recovery

Why it happens: Status reporting was confused with a safe remediation decision.
How to fix it: Classify failed progress and select an accountable response.
Prevent it next time: Define abort ownership before rollout.

Check your understanding

1. Three replicas use maxSurge one and maxUnavailable zero. What extra planning is required?

Show worked solution

Allow placement and dependency capacity for a temporary fourth Pod, with compatible storage and identity. Preserve meaningful readiness and graceful termination. The settings constrain controller behavior but cannot guarantee zero failures or supply missing node resources.

2. The controller reports available replicas. Why still observe a user journey?