Helm charts and releases: rendering, values, hooks and rollback limits
Distinguish a Helm chart from a release, inspect rendered manifests and understand how values and hooks affect upgrades. Learn why release rollback cannot undo database side effects.
TL;DR: A chart packages Kubernetes templates and defaults. A release is a named installation managed through Helm's lifecycle. Rendering produces manifests; applying them changes the cluster. Hooks and external state can make an upgrade's effects broader than its stored release revision.
Four identities belong in the release record
Suppose a chart called checkout has chart version 1.6.0, its application image is 4.8.2, and it is installed as release checkout-prod. An upgrade may create release revision 12. Those four values answer different questions: packaging version, application identity, installation name and operation history.
The chart's appVersion is descriptive metadata. It does not automatically force every template to use that image version. Inspect the actual image field produced by templates and values. The chart format documentation explains these metadata fields and how templates and dependencies are packaged.
The two paths share rendering concepts but differ in lifecycle ownership. When Argo CD uses Helm to generate manifests, do not assume an independently managed Helm release history exists for that Application.
Review the rendered result
The following commands assume an existing local chart at ./checkout-chart and a reviewed values file. They render and inspect locally; the helm lint command checks chart structure, while helm template does not prove that a target cluster will admit the objects.
helm lint ./checkout-chart -f values-production.yaml
helm template checkout-prod ./checkout-chart \
--namespace shop -f values-production.yaml > rendered.yaml
Treat rendered.yaml as sensitive if values or templates include secrets. Do not upload it to a public build log. Review resource identities, namespace, selectors, image references, requests and security settings. Validate against the intended API versions and admission policies in a suitable test environment.
A chart can render syntactically valid YAML that is operationally wrong. A Service selector may no longer match the Deployment, or an environment-specific value may point at the wrong database. Testing the rendered relationships catches problems that template syntax checks cannot.
Values form a configuration interface
| Change | Why the reviewer should care | Useful verification |
|---|---|---|
| Rename a documented value key | Existing users may silently retain a default | Schema validation and migration notes |
| Change a default replica count | Capacity can change on upgrade | Compare rendered output using current values |
| Introduce a dependency chart | New resources and privileges may appear | Review dependency versions and rendered objects |
| Change a Secret template | Credentials can be regenerated or exposed | Test rotation and application reload behavior |
| Change a selector | Resource immutability or traffic membership may be affected | Inspect object-specific API constraints |
Use a values schema where appropriate to catch wrong types and required configuration. A schema still cannot establish that a hostname points to the correct production dependency. Explain environmental assumptions in the chart's own documentation.
Avoid casually reusing old values across every upgrade. A removed or renamed value can preserve an unintended setting or stop affecting the output. Compare the installed configuration with the proposed rendering under the exact upgrade command you will use.
Hooks introduce separate work
A pre-upgrade hook might run a migration Job before workloads change. If that Job alters data and the rollout then fails, restoring an older Pod template does not reverse the migration. Make the migration compatible with the previous application version during the recovery window.
The Helm hooks documentation also warns that hook-created resources are not managed as ordinary release resources. Define cleanup through supported hook deletion policy or Job TTL behavior. Otherwise completed Jobs and their logs can accumulate, potentially retaining sensitive output.
Hooks must tolerate retries and partial execution according to their operation. A migration that succeeds but loses its completion signal can be attempted again. Use the database's migration bookkeeping and safe change design to prevent duplicate effects; “Helm runs it” is not a transaction guarantee.
Rollback is a deployment operation
Inspect release history and the selected revision before an authorized rollback. Check the earlier chart, values, image identity and current external schema. The previous release may refer to an image tag that has moved, so immutable references matter even for historical manifests.
If an upgrade fails because a new image cannot start, restoring the previous compatible revision may recover service quickly. If the upgrade removed a database column the previous version needs, rolling back code can create another failure. The rollback compatibility concept provides a matrix for deciding which previous version remains viable.
Explain the surprising upgrade
Self-check: the chart's appVersion changes from 4.8.2 to 4.9.0, yet Pods still run the old image. What would you inspect?
Read the rendered Deployment and the values that supply its image field. The template may use a separate image.tag, an explicit digest, or an override from the environment file. Then confirm whether the Pod template changed and whether a rollout occurred. Metadata alone does not establish the deployed artifact.
Continue with Argo CD architecture if GitOps owns the release, or pipeline architecture if an imperative deployment job invokes Helm.