Inside Helm - How Charts, Releases, and State Work in Kubernetes

What’s Inside a Helm Chart#

A Helm chart is a package. It describes how your app should land on Kubernetes, and it’s structured and predictable. Do it right and it becomes gorgeously reusable, too.

1
my-chart/
2
  Chart.yaml              # metadata (name, version, dependencies, etc.)
3
  values.yaml             # default configuration values
4
  templates/              # Go templates for Kubernetes manifests
5
    _helpers.tpl          # reusable named templates and functions
6
  charts/                 # subcharts (dependencies)
7
  files/                  # arbitrary files used in templates
8
  crds/                   # CustomResourceDefinitions (installed first)
9
  .helmignore             # like .gitignore for packaging

Picture it as the blueprint for your app. You flex it through values.yaml, and you can override the defaults at deploy time whenever you like.

Pro tip: CRDs in the crds/ directory are:

• installed first,
• not templated,
• and never upgraded or deleted — this protects existing Custom Resources and data.

What Actually Happens When You Run helm install#

There’s a sequence here, and it matters. Run helm install and Helm doesn’t just “apply some YAML.” It walks through clear steps:

• Loads the chart (local or remote).
• Merges values from multiple sources:
  • base values.yaml;
  • any additional files: -f base.yaml -f prod.yaml (left-to-right; later overrides earlier);
  • inline flags: --set, --set-string, --set-file, --set-json (these always take precedence).
• Renders Go templates into complete Kubernetes manifests.
• Applies them to the cluster.

Clean install? Helm just creates the resources. Easy.

Things get a little more interesting if the resources already exist. When they carry the correct Helm annotations (meta.helm.sh/*, app.kubernetes.io/managed-by=Helm), Helm will happily adopt them. If they don’t, here’s what you get:

1
Error: invalid ownership metadata

During upgrades or rollbacks, the story changes again. Helm runs a three-way strategic merge, comparing the previous manifest, the new manifest, and the current cluster state. That whole comparison happens client-side, through client-go.

Where Helm Stores Release State#

Every Helm release lives inside your cluster. No external DBs. No magic. Promise.

By default, your release info goes into a Kubernetes Secret. You can swap that out for a ConfigMap or a SQL driver (PostgreSQL) if you’d rather.

Default object structure:

1
kind: Secret
2
type: helm.sh/release.v1
3
metadata:
4
  name: sh.helm.release.v1.<release>.v<revision>
5
  namespace: <release-namespace>

Now, the .data.release field. This is where the good stuff hides: a base64-encoded, gzip-compressed blob holding the chart archive, the rendered manifests, your merged values, hooks, plus release metadata like revision, timestamps, and status.

One quirk worth knowing. Kubernetes already base64-encodes Secret data, and the release payload also includes encoded sections of its own, so you end up with nested encoding. Encoding inside encoding. Cute, in a confusing way.

Heads up: etcd enforces a ~1 MiB limit for Secret data. Bump into this:

1
Too long: must have at most 1048576 characters

and it’s time to switch to SQL storage:

1
export HELM_DRIVER=sql
2
export HELM_DRIVER_SQL_CONNECTION_STRING=postgresql://user:pass@host/db

Labels and Annotations#

Helm labels everything it touches so it can track ownership down to the detail.

Added automatically:

1
app.kubernetes.io/managed-by=Helm
2
meta.helm.sh/release-name=<release-name>
3
meta.helm.sh/release-namespace=<namespace>

Best-practice labels (usually added by chart templates):

1
app.kubernetes.io/instance=<release-name>
2
helm.sh/chart=<chart-name>-<version>

When these don’t line up during an upgrade, Helm refuses to take ownership. And that, darling, is exactly where the classic invalid ownership metadata error comes from.

What Is a Helm Release?#

A release is one installed instance of a chart, with a specific set of values, living in a namespace.

Every change you make becomes a new revision. Install, upgrade, rollback, doesn’t matter. Each one gets stored right there in your cluster. No external database. No API extension. Just plain old Kubernetes objects, quietly doing their job.

The Three-Way Merge Explained#

Here’s what Helm lines up side by side when you upgrade:

• the previous rendered manifest,
• the new manifest (after your changes),
• the current live resources.

From those three, it works out a three-way strategic merge patch and applies only what actually changed. Less disruption that way, and your manual tweaks survive where they can.

NOTE

This logic runs client-side, not via Server-Side Apply. For CRDs or unstructured resources, Kubernetes uses JSON merge-patch, which can behave slightly differently.

Namespaces: Release vs Target#

Helm splits namespaces into two flavors:

• Release namespace — where Helm stores its Secret or ConfigMap.
• Target namespaces — where chart resources are deployed (can be multiple).
• --create-namespace only creates the release namespace (the one you pass with --namespace).

Got a chart that spreads across namespaces? Then create them yourself, or template them inside the chart.

Tip: Try not to hardcode metadata.namespace unless you genuinely need to. Otherwise helm template | kubectl apply might quietly shove your resources into default.

Storage Drivers#

Helm gives you a few backends for storing release state:

1
export HELM_DRIVER=secret      # default (encoded, secure)
2
export HELM_DRIVER=configmap   # readable, not encrypted
3
export HELM_DRIVER=sql         # PostgreSQL – best for large releases
4
export HELM_DRIVER=memory      # ephemeral, for tests only

Managing Release History#

Helm hangs onto all revisions unless you tell it not to. So put a cap on it:

1
helm upgrade --history-max 10 ...
2
export HELM_MAX_HISTORY=10

Want to poke through the history? Anytime:

1
helm history <release>
2
helm get values <release>
3
helm get manifest <release>

TL;DR#

Helm isn’t magic. It’s just clean engineering. Every time you fire off helm install, it:

• loads, merges, and renders templates,
• stores state inside your cluster,
• tags resources for ownership tracking,
• applies three-way strategic merges on upgrade,
• manages revisions — all with zero external dependencies.

Once the inner workings click for you, Helm stops feeling like a mystery box. It starts feeling like your favorite DevOps assistant. 💖

Quick Debug Tip#

1
helm ls -A
2
kubectl get secrets -A -l "owner=helm" -l "status=deployed"

Great for a fast audit, or just snooping on what Helm’s been up to lately.