Helm / Intermediate: authoring and lifecycle contracts / Lesson 11

Upgrades, value history and rollback

Evaluate a release change across old and new inputs, object identities, application compatibility and recovery boundaries before choosing a lifecycle operation.

About 5 min readContent reviewed 2026-10-28

On this page

Lesson goals

Compare release history with intended desired state.
Explain reuse and reset decisions for upgrade values.
Distinguish resource rollback from external state recovery.

Compare three sets of evidence

An upgrade review needs the previously approved chart and values, the newly proposed chart and values and relevant observed environment state. The old and new desired manifests explain intent; observations explain drift and current constraints. Looking only at the new package misses removed resources, changed names and immutable fields. Looking only at live objects loses the configuration source and release history. Use a synthetic change inventory before any operation: unchanged identity with modified fields, new identity, removed identity and externally owned dependency. Each category raises different questions about compatibility, retention and recovery.

Make values policy explicit

Helm upgrade offers options that affect how previous values and new defaults participate. Reusing previous values can preserve intentional settings but also retain obsolete keys; resetting values can adopt new defaults but lose a prior customization if it is not supplied again. Do not choose by habit or infer behavior from an omitted flag without checking the selected client documentation. Prefer a reviewed desired input contract with explicit migration decisions. The first example is a change record, not a command. It makes a retained port and removed obsolete field visible before discussing an operational action.

text A values migration decision record

previous input: service.port=8080, legacyMode=true
proposed contract: service.port=8080, feature.mode=standard
intentional removal: legacyMode
separate check: new templates consume feature.mode

The record establishes intended inputs only. It does not claim a real release history or execute an upgrade.

Separate readiness and transactions

Wait-related options can make Helm observe selected Kubernetes readiness conditions before declaring success. Atomic upgrade behavior can attempt rollback on failure. Neither mechanism turns a multi-resource application change into a database transaction. A migration Job might already have altered stored data, an external message may already have been sent or an old application version may no longer understand the new schema. Timeouts also describe observation limits rather than the complete state of the world. Define application-specific success and a compatible recovery route in addition to Helm lifecycle status.

Inspect identity differences

An object name change is not an in-place edit, and some fields cannot be changed on an existing object. A forceful replacement option may recreate resources and affect availability or storage associations; it is not a universal fix for upgrade errors. The Python example compares synthetic identity sets and lists one added and one removed ConfigMap name. It does not predict Helm deletion behavior, hooks or retention annotations. Its purpose is to surface questions early: who owns the old object, do references move together and what application state remains coupled to that identity?

python Synthetic identity inventory

old = {"ConfigMap/preview-settings", "Service/preview-catalog"}
new = {"ConfigMap/preview-settings-v2", "Service/preview-catalog"}
print(sorted(new - old))
print(sorted(old - new))

Expected output

['ConfigMap/preview-settings-v2']
['ConfigMap/preview-settings']

The two lists show desired-set differences only; no Kubernetes objects or release records are accessed.

Plan recovery before selection

A rollback selects an earlier release revision and creates another lifecycle event; it does not erase history or automatically restore external data. Before relying on rollback, verify that the target chart, values, image and data format remain usable. A forward fix may be safer when state has moved irreversibly, but that decision belongs to the application recovery design. Preserve evidence and stop competing changes while investigating an authorized environment. Here no lifecycle command runs. The course teaches the review questions so a real change can have a concrete, application-aware plan instead of a hopeful command.

Common errors and fixes

Obsolete values survive an upgrade unexpectedly

Why it happens: Previous values were reused without an explicit migration inventory.
How to fix it: Compare accepted old keys with the new interface and remove or migrate them intentionally.
Prevent it next time: Version values migration examples with chart changes.

Atomic is interpreted as a database transaction

Why it happens: Resource rollback was assumed to reverse external side effects.
How to fix it: Design data-compatible application recovery and independent side-effect handling.
Prevent it next time: Classify every migration and hook by reversibility.

A force option is proposed for every immutable-field error

Why it happens: Recreation consequences and ownership were not reviewed.
How to fix it: Identify the immutable field and plan a specific supported migration.
Prevent it next time: Compare object identities and immutable fields before operation selection.

Check your understanding

1. The new chart removes legacyMode. Why might reusing values hide a migration problem?

Show worked solution

The old key can remain in the effective configuration even if new templates ignore it, giving reviewers false confidence that the previous behavior is preserved. Alternatively a new strict schema may reject it. Compare old and new interfaces explicitly, replace the old input with its documented successor and review the generated behavior rather than treating retained keys as compatibility evidence.

2. A migration writes a new data format and then readiness fails. What must a recovery decision consider?