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.
Associate the source revision, image digest and configuration source so a later investigation can reproduce the intended environment.
- Source revision to Rendered resourcesrendered source
- Image digest to Pod templateimage reference
Read the complete visual sequence
- Record the release inputs
Associate the source revision, image digest and configuration source so a later investigation can reproduce the intended environment.
- Make configuration part of intent
A versioned generated configuration reference can change the Pod template when configuration changes, making the rollout explicit.
- 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.
- 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.
- ConfigMap data updated
The API object changes without altering the Pod template hash.
- Existing environment stays old
A process using environment-derived configuration keeps its startup value; mounted files may update but still need reload handling.
- 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.
The controller can start an extra candidate while keeping the old replicas, provided requests and quota fit.
- Deployment to New replicasurge=1
Read the complete visual sequence
- Create one surge instance
The controller can start an extra candidate while keeping the old replicas, provided requests and quota fit.
- Wait for stable readiness
The candidate must satisfy readiness and the available interval before it counts toward replacement progress.
- 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.
- 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.
- Old service remains available
maxUnavailable=0 preserves old available replicas while the surge candidate fails.
- Progress deadline exposes stall
The Deployment reports failed progress after the configured deadline; that condition does not automatically restore a previous version.
- 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