Appearance

Release configuration and safe delivery

Promote an explicit application configuration, protect rollout headroom and verify a compatible recovery path.

What you will understand

  • Define a release as code, image, configuration and dependencies
  • Coordinate readiness, rollout budgets and autoscaler ownership
  • Choose rollback or roll-forward using application and data compatibility evidence

Builds on: HPA, VPA, and node autoscaling

Mental model: a release is more than a changed image

A reproducible release configuration identifies the application image, rendered workload resources, non-secret configuration references, credential-delivery method and required dependencies. Pin a production image by an approved immutable digest so that the same identifier means the same content. Keep the source revision and rendered artifact associated with the release. A mutable tag can be convenient in a training exercise, but it weakens the claim that tomorrow’s deployment is identical to today’s.

Configuration also has lifecycle semantics. A Deployment creates a new ReplicaSet when its Pod template changes. Changing a ConfigMap’s data without changing that template does not automatically trigger a rollout. Environment-derived configuration is fixed for an existing process, while mounted configuration can update eventually but still needs application reload support. A subPath mount has different update behavior. Versioned generated ConfigMap names or a deliberate template annotation can make configuration changes part of an explicit rollout rather than an invisible side effect.

Record the whole input set that a process will consume

Show immutable image identity, rendered manifests and versioned configuration producing an explicit Pod-template revision.

Ownership viewStep 1 of 4
Record the release inputsAssociate the source revision, image digest and configuration source so a later investigation can reproduce the intended environment.. Source revision, Reviewed application/configuration source, active. Image digest, Immutable application content, ready. Rendered resources, Concrete API manifests, active. Versioned ConfigMap, Non-secret configuration reference, idle. Pod template, Image + configuration references, idle. Running process, Consumes startup or reload state, idleSource revision: Reviewed application/configuration source
Source revisionReviewed application/configuration sourceIn focus
Image digest: Immutable application content
Image digestImmutable application contentReady
Rendered resources: Concrete API manifests
Rendered resourcesConcrete API manifestsIn focus
Versioned ConfigMap: Non-secret configuration reference
Versioned ConfigMapNon-secret configuration referenceContext
Pod template: Image + configuration references
Pod templateImage + configuration referencesContext
Running process: Consumes startup or reload state
Running processConsumes startup or reload stateContext
Source revisionReviewed application/configuration sourceIn focus
Image digestImmutable application contentReady
Rendered resourcesConcrete API manifestsIn focus
Versioned ConfigMapNon-secret configuration referenceContext
Pod templateImage + configuration referencesContext
Running processConsumes startup or reload stateContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Mutable ConfigMap changes without a rollout
Record the release inputs

Associate the source revision, image digest and configuration source so a later investigation can reproduce the intended environment.

Read the complete visual sequence
  1. Record the release inputs

    Associate the source revision, image digest and configuration source so a later investigation can reproduce the intended environment.

  2. Make configuration part of intent

    A versioned generated configuration reference can change the Pod template when configuration changes, making the rollout explicit.

  3. Create a new template revision

    A changed template produces new Pods through a new ReplicaSet. Updating only mutable ConfigMap data does not necessarily do this.

  4. Verify consumed configuration

    Check that the process uses the intended image and configuration without revealing credentials. Mounted reload and startup environment have different behavior.

Mutable ConfigMap changes without a rollout

Referenced data changes while the Deployment template remains identical.

  1. ConfigMap data updated

    The API object changes without altering the Pod template hash.

  2. Existing environment stays old

    A process using environment-derived configuration keeps its startup value; mounted files may update but still need reload handling.

  3. Make the transition explicit

    Use a controlled reload or versioned reference and rollout, then verify process behavior. Deployment undo alone does not recover arbitrary ConfigMap history.

About this model

Credential values are external to the release artifact; references and delivery method are recorded.

Walkthrough: trade surge capacity against unavailable replicas

The following Deployment strategy fragment assumes three healthy application replicas, a useful readiness probe and enough capacity for an extra Pod. It belongs under the Deployment’s spec; the readiness fragment belongs in the application container. A zero-unavailable rollout still needs headroom and a backend capable of supporting both versions at once.

# Deployment spec fragment.
replicas: 3
minReadySeconds: 10
progressDeadlineSeconds: 300
strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1
    maxUnavailable: 0
# Container probe fragment; the application must implement /ready.
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 2
  periodSeconds: 5

Readiness says whether a Pod should receive ordinary Service traffic. It should represent the application’s ability to serve, while avoiding fragile checks that make every replica unready for a minor optional dependency. minReadySeconds requires a stable ready interval before counting a new replica as available for rollout progress. progressDeadlineSeconds exposes a stalled rollout condition; it does not by itself perform an automatic rollback. The controller can wait indefinitely for a repair unless external delivery tooling makes a decision.

Readiness gates replacement; evidence gates promotion

Follow a surge Pod through readiness, availability, customer verification and a compatibility-aware recovery decision.

Lifecycle viewStep 1 of 4
Create one surge instanceThe controller can start an extra candidate while keeping the old replicas, provided requests and quota fit.. Old replicas, Three available instances, ready. New replica, Candidate template, active. Readiness gate, Can serve + minReadySeconds, idle. Deployment, Controls replacement progress, idle. Customer probe, Safe changed-path verification, idle. Data compatibility, Old/new schema and side effects, idleOld replicas: Three available instances
Old replicasThree available instancesReady
New replica: Candidate template
New replicaCandidate templateIn focus
Readiness gate: Can serve + minReadySeconds
Readiness gateCan serve + minReadySecondsContext
Deployment: Controls replacement progress
DeploymentControls replacement progressContext
Customer probe: Safe changed-path verification
Customer probeSafe changed-path verificationContext
Data compatibility: Old/new schema and side effects
Data compatibilityOld/new schema and side effectsContext
Old replicasThree available instancesReady
New replicaCandidate templateIn focus
Readiness gateCan serve + minReadySecondsContext
DeploymentControls replacement progressContext
Customer probeSafe changed-path verificationContext
Data compatibilityOld/new schema and side effectsContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Candidate never becomes ready
Create one surge instance

The controller can start an extra candidate while keeping the old replicas, provided requests and quota fit.

Read the complete visual sequence
  1. Create one surge instance

    The controller can start an extra candidate while keeping the old replicas, provided requests and quota fit.

  2. Wait for stable readiness

    The candidate must satisfy readiness and the available interval before it counts toward replacement progress.

  3. Replace gradually and verify

    After availability, the controller can remove an old instance and continue. Independently run a safe customer-path check and observe telemetry.

  4. Choose compatible recovery

    If evidence fails, compare rollback and roll-forward against data/configuration compatibility. A template rollback cannot reverse every external side effect.

Candidate never becomes ready

The rollout has capacity but the new version fails its readiness condition.

  1. Old service remains available

    maxUnavailable=0 preserves old available replicas while the surge candidate fails.

  2. Progress deadline exposes stall

    The Deployment reports failed progress after the configured deadline; that condition does not automatically restore a previous version.

  3. Investigate and act deliberately

    Read candidate logs, events and effective configuration, then apply a compatible repair or chosen rollback and repeat the customer probe.

About this model

Three replicas, maxSurge=1, maxUnavailable=0 and sufficient temporary capacity.

Practice: promote only the behavior you actually checked

kubectl diff -k overlays/training
kubectl apply -k overlays/training
kubectl rollout status deployment/api -n learning --timeout=300s
kubectl get deployment,replicaset,pod -n learning -l app=api
kubectl get endpointslices -n learning \
  -l kubernetes.io/service-name=api
kubectl rollout history deployment/api -n learning
# Only after choosing a compatible recovery action:
# kubectl rollout undo deployment/api -n learning --to-revision=REVISION

Use the delivery lab to record the intended revision, rendered diff, ready endpoints and one real request result. Compare error rate, latency and saturation against the previous version using the installed telemetry, without claiming results from an absent monitoring stack. A rollout command can finish while an important business path remains broken. A smoke test should exercise the changed path with safe data and a known expected response.

Promotion can mean proceeding from a test environment, increasing traffic to a candidate or finishing a rollout. A canary needs a routing or replica strategy that actually controls the desired traffic share; creating a second Deployment alone does not guarantee a chosen percentage. Keep evaluation windows long enough to cover relevant startup and workload behavior. Define an operator decision and recovery path before sending consequential traffic to a new version.

Pitfalls: rollback has a data and configuration compatibility boundary

A workload rollback restores a prior Pod template revision, not every ConfigMap, external message or database migration. Use backward-compatible schema changes, staged migration patterns and explicit release records when old and new versions overlap. Rolling forward may be safer than restoring binaries that cannot read newly written data. Do not label a successful ReplicaSet switch as a full business recovery until the customer path and data state are verified.

Resource and ownership controls also affect delivery. Include surge in quota and node-capacity calculations. Avoid reapplying a fixed replica count when HPA should own it. Ensure PDB expectations, rollout strategy and maintenance windows describe compatible availability goals, recognizing that PDBs do not directly govern Deployment rolling updates. Validate required APIs against the target cluster before upgrading charts or controllers; a manifest using a removed API fails before its application behavior can be tested.

Check your understanding

A new ConfigMap value breaks the application, but the Deployment Pod template did not change. Will rollout undo necessarily restore the old value?

No. Deployment revision history tracks Pod template changes, not an arbitrary history of all referenced ConfigMap data. Restore the intended configuration through its recorded source or use versioned configuration references as part of a new compatible release. Then verify what each running process actually consumes before declaring recovery.

Continue into the advanced API lessons to understand admission, watches and field ownership beneath these delivery workflows. Retain the intermediate lab evidence as a concrete map of where each operational guarantee ends.

Primary documentation

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.