k8wiz
All graphs

Helm graph

A Helm release: chart, values, revisions and the objects Helm owns

What helm upgrade --install does in the cluster: the chart pulled from an OCI registry, values merged over its defaults, a hook Job, the objects carrying Helm's ownership labels, and one release Secret per revision.

Helm is a client. It renders a chart's templates with your values, applies the result, and writes down what it did. That record, one Secret per revision in the release's namespace, is all the state Helm has.

This graph shows what one helm upgrade --install web leaves in the shop namespace, and what a later upgrade or rollback reads.

Interactive graph

Click a resource to see what it does, or follow the setup step by step.

Outside the clusterYou write itMade by a tooltrafficreferencescreatesselects by label

How it works

All 9 resources and what they do

Helm chart oci://ghcr.io/acme/charts/web:1.5.0
Templates, default values.yaml and Chart.yaml, stored in a registry as an OCI artifact. --version picks the tag.
Values file values-prod.yaml
Your overrides. Helm merges them over the chart's defaults, then applies --set on top. Only what you supply is stored with the release as its user values.
helm upgrade --install web
Renders the templates, compares the result with the last revision's manifest and patches the cluster. With --wait it then watches the workloads until they are ready or --timeout passes.
Secret sh.helm.release.v1.web.v2v1
The previous revision, now superseded. It holds that revision's chart, values and rendered manifest, which is what helm rollback web 2 applies again.
Secret sh.helm.release.v1.web.v3v1
The new revision, of type helm.sh/release.v1. Helm writes it as pending-upgrade before it touches anything and sets it to deployed at the end. While it says pending, other upgrades refuse to start.
Job web-migratebatch/v1
A pre-upgrade hook from the chart. Helm creates it and waits for it to finish before it applies the rest. Hooks are not part of the release manifest, so an uninstall doesn't remove them unless a delete policy says so.
ConfigMap webv1
Rendered from a template. A checksum of it sits in an annotation on the Pod template, so changing a value here rolls the Pods.
Deployment webapps/v1
Carries app.kubernetes.io/managed-by: Helm and the annotations meta.helm.sh/release-name and meta.helm.sh/release-namespace. Helm refuses to touch an object of this name that lacks them.
Service webv1
Part of the same manifest, with the same ownership metadata. If a later chart version drops it, the next upgrade deletes it.

Common mistakes

  • A CI job timeout shorter than Helm's --timeout kills Helm with the revision still pending-upgrade. Every later upgrade fails until helm rollback clears it.
  • Without --wait, Helm 4 waits for hooks and not for your Pods. The command can report success while the rollout is failing.
  • An upgrade with no -f or --set reuses the stored values. One with any of them starts again from the chart's defaults unless you pass --reuse-values.
  • Helm won't adopt an object it didn't create. exists and cannot be imported into the current release goes away once the object has the managed-by label and both meta.helm.sh annotations.
  • helm history web keeps ten revisions by default. A rollback target older than that is gone.

The manifests you write

Everything above that is marked "You write it", in one file. The rest comes from add-ons and controllers.

replicaCount: 3

image:
  tag: "2.1"

greeting: Hello from production

Keep going

Helm quizTest yourself on charts, templates, values, releases, hooks, repositories and Helm 4.Try it in the playgroundFix a Helm release stuck in pending-upgradeTry it in the playgroundAdopt running resources into a Helm release without downtimeTry it in the playgroundFix a Flux HelmRelease that never becomes ReadyArticleHelm 4.3: what changed and how to upgradeArticleHow to fix a Helm release stuck in pending-upgradeArticleExploring Helm 4: New Features, Changes, and Implications for Kubernetes Users

More graphs